@agence-zef/astro 0.3.1 → 0.5.0

package/components/Accordion.astro

@@ -0,0 +1,61 @@
+---
+/**
+ * Accordéon natif (`<details>` / `<summary>`), sans JavaScript ni style imposé : classes
+ * `zef-accordion`, `zef-accordion__item`, `__summary`, `__content`, habillées par
+ * `@agence-zef/astro/styles.css` (ouverture animée) ou par le CSS du site.
+ *
+ * Deux usages : `items` (une liste du CMS : `{ summary, html }` ou `{ summary, text }`), ou
+ * des `<AccordionItem>` en contenu. `exclusive` : un seul élément ouvert à la fois (attribut
+ * `name` natif). `faq` : ajoute les données structurées FAQPage pour Google (avec `items`).
+ */
+import RichText from "./RichText.astro";
+
+type Item = { summary: string; html?: string | null; text?: string | null; open?: boolean };
+
+interface Props {
+	items?: Item[];
+	exclusive?: boolean;
+	faq?: boolean;
+	/** Nom du groupe exclusif, à reprendre dans les `<AccordionItem name>` en contenu. */
+	name?: string;
+	class?: string;
+}
+
+const { items, exclusive = false, faq = false, class: className } = Astro.props;
+const name =
+	Astro.props.name ?? (exclusive ? `zef-acc-${Math.random().toString(36).slice(2, 8)}` : undefined);
+const strip = (html: string) =>
+	html
+		.replace(/<[^>]*>/g, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+const faqData =
+	faq && items?.length
+		? {
+				"@context": "https://schema.org",
+				"@type": "FAQPage",
+				mainEntity: items
+					.filter((i) => i.summary)
+					.map((i) => ({
+						"@type": "Question",
+						name: i.summary,
+						acceptedAnswer: { "@type": "Answer", text: i.text ?? strip(i.html ?? "") },
+					})),
+			}
+		: null;
+---
+
+<div class:list={["zef-accordion", className]}>
+	{
+		items?.map((item) => (
+			<details class="zef-accordion__item" name={name} open={item.open}>
+				<summary class="zef-accordion__summary">{item.summary}</summary>
+				<div class="zef-accordion__content">
+					{item.html ? <RichText html={item.html} /> : item.text ? <p>{item.text}</p> : null}
+				</div>
+			</details>
+		))
+	}
+	<slot />
+</div>
+{faqData && <script type="application/ld+json" is:inline set:html={JSON.stringify(faqData).replace(/</g, "\\u003c")} />}

package/components/AccordionItem.astro

@@ -0,0 +1,23 @@
+---
+/**
+ * Élément d'accordéon (`<details>`), à mettre dans `<Accordion>` ou seul. Titre : `summary`, ou
+ * le contenu du slot `summary` (icône, mise en forme). `name` : groupe exclusif (un seul ouvert).
+ */
+interface Props {
+	summary?: string;
+	name?: string;
+	open?: boolean;
+	class?: string;
+}
+
+const { summary, name, open = false, class: className } = Astro.props;
+---
+
+<details class:list={["zef-accordion__item", className]} name={name} open={open}>
+	<summary class="zef-accordion__summary">
+		{Astro.slots.has("summary") ? <slot name="summary" /> : summary}
+	</summary>
+	<div class="zef-accordion__content">
+		<slot />
+	</div>
+</details>

package/components/Checkbox.astro

@@ -0,0 +1,20 @@
+---
+/**
+ * Case à cocher (ou bouton radio avec `type="radio"`) avec son libellé, classe `zef-check`.
+ * Le libellé : `label`, ou le contenu (lien vers les conditions, mise en forme).
+ */
+import type { HTMLAttributes } from "astro/types";
+
+type Props = Omit<HTMLAttributes<"input">, "class" | "type"> & {
+	label?: string;
+	type?: "checkbox" | "radio";
+	class?: string;
+};
+
+const { label, type = "checkbox", class: className, ...rest } = Astro.props;
+---
+
+<label class:list={["zef-check", className]}>
+	<input {...rest} type={type} />
+	<span>{Astro.slots.has("default") ? <slot /> : label}</span>
+</label>

package/components/Dialog.astro

@@ -0,0 +1,72 @@
+---
+/**
+ * Fenêtre modale native (`<dialog>`), sans style imposé : classes `zef-dialog`,
+ * `zef-dialog__panel`, `zef-dialog__close`, habillées par `@agence-zef/astro/styles.css`
+ * (variables `--zef-*`) ou par le CSS du site.
+ *
+ * Ouverture : n'importe quel élément avec `data-zef-open="<id>"` (bouton, lien). Fermeture :
+ * Échap, clic sur le voile, ou un élément `data-zef-close` dans la fenêtre. La page en dessous
+ * ne défile plus pendant l'ouverture ; animations d'ouverture et de fermeture via
+ * `[open]` / `[data-closing]`, coupées si le visiteur réduit les animations.
+ */
+interface Props {
+	id: string;
+	/** Titre lu par les lecteurs d'écran si la fenêtre n'a pas de titre visible. */
+	label?: string;
+	/** Bouton de fermeture en haut à droite (défaut : oui) et son libellé accessible. */
+	closeButton?: boolean;
+	closeLabel?: string;
+	class?: string;
+}
+
+const { id, label, closeButton = true, closeLabel = "Fermer", class: className } = Astro.props;
+---
+
+<dialog id={id} class:list={["zef-dialog", className]} aria-label={label} data-zef-dialog>
+	<div class="zef-dialog__panel">
+		{
+			closeButton && (
+				<button type="button" class="zef-dialog__close" data-zef-close aria-label={closeLabel}>
+					<svg width="20" height="20" viewBox="0 0 24 24" aria-hidden="true">
+						<path d="M18 6 6 18M6 6l12 12" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" />
+					</svg>
+				</button>
+			)
+		}
+		<slot />
+	</div>
+</dialog>
+
+<style is:global>
+	/* Comportement, pas habillage : la page ne défile plus derrière une fenêtre ouverte. */
+	html:has(dialog[data-zef-dialog][open]) {
+		overflow: hidden;
+	}
+</style>
+
+<script>
+	import { closeDialog } from "@agence-zef/astro/ui";
+
+	document.addEventListener("click", (event) => {
+		const target = event.target as Element;
+		const opener = target.closest<HTMLElement>("[data-zef-open]");
+		if (opener) {
+			const dialog = document.getElementById(opener.dataset.zefOpen ?? "");
+			if (dialog instanceof HTMLDialogElement) {
+				event.preventDefault();
+				dialog.showModal();
+			}
+			return;
+		}
+		const closer = target.closest("[data-zef-close]");
+		const dialog = (closer ?? target).closest("dialog[data-zef-dialog]");
+		// Un clic sur le voile atteint le <dialog> lui-même, pas son panneau.
+		if (dialog instanceof HTMLDialogElement && (closer || target === dialog)) closeDialog(dialog);
+	});
+	for (const dialog of document.querySelectorAll<HTMLDialogElement>("dialog[data-zef-dialog]")) {
+		dialog.addEventListener("cancel", (event) => {
+			event.preventDefault();
+			closeDialog(dialog);
+		});
+	}
+</script>

package/components/Field.astro

@@ -0,0 +1,27 @@
+---
+/**
+ * Champ de formulaire codé dans le site : libellé, contrôle (slot), aide et erreur, avec les
+ * classes partagées par tous les formulaires de `@agence-zef/astro` (`zef-field`, `zef-label`,
+ * `zef-help`, `zef-error`). `for` : identifiant du contrôle.
+ */
+interface Props {
+	label: string;
+	for?: string;
+	help?: string;
+	error?: string;
+	required?: boolean;
+	class?: string;
+}
+
+const { label, for: htmlFor, help, error, required = false, class: className } = Astro.props;
+---
+
+<div class:list={["zef-field", className]} data-invalid={error ? "" : undefined}>
+	<label class="zef-label" for={htmlFor}>
+		{label}
+		{required && <span class="zef-required" aria-hidden="true"> *</span>}
+	</label>
+	<slot />
+	{help && <p class="zef-help">{help}</p>}
+	<p class="zef-error" role="alert" hidden={!error}>{error}</p>
+</div>

package/components/Image.astro

@@ -10,18 +10,30 @@ import type { Media } from "@agence-zef/schema";
 interface Props {
 	media: Media | null;
 	class?: string;
-	/** `eager` pour l'image principale de la page. */
+	/** `eager` pour une image visible dès l'ouverture de la page. */
 	loading?: "lazy" | "eager";
+	/**
+	 * Image principale de la page (LCP, en général celle du hero) : chargée tout de suite et en
+	 * priorité (`fetchpriority="high"`). Une seule par page.
+	 */
+	priority?: boolean;
 	/** Largeur affichée (`(min-width: 48rem) 33vw, 100vw`) : active le `srcset`. */
 	sizes?: string;
 }
 
-const { media, class: className, loading = "lazy", sizes } = Astro.props;
+const { media, class: className, priority = false, sizes } = Astro.props;
+const loading = priority ? "eager" : (Astro.props.loading ?? "lazy");
+const fetchpriority = priority ? "high" : undefined;
+// Proportions réservées même si le CSS du site force `width: auto` (pas de décalage au chargement).
+const style =
+	media?.width && media.height ? `aspect-ratio: ${media.width} / ${media.height}` : undefined;
 const OPTIMIZED = ["image/jpeg", "image/png", "image/webp", "image/avif"];
 const optimize = Boolean(
 	media?.width && media.height && media.mime && OPTIMIZED.includes(media.mime),
 );
-const STEPS = [480, 800, 1200, 1600, 2400];
+// Largeurs générées pour le `srcset` : assez serrées pour qu'un mobile ne télécharge pas une
+// image deux fois trop grande.
+const STEPS = [320, 480, 640, 800, 960, 1200, 1600, 2000, 2400];
 const widths =
 	sizes && media?.width
 		? [...STEPS.filter((w) => w < (media.width as number)), media.width]
@@ -37,10 +49,12 @@ const widths =
 				width={media.width as number}
 				height={media.height as number}
 				loading={loading}
-				decoding="async"
+				fetchpriority={fetchpriority}
+				decoding={priority ? "sync" : "async"}
 				sizes={sizes}
 				widths={widths}
 				class={className}
+				style={style}
 			/>
 		) : (
 			<img
@@ -49,9 +63,11 @@ const widths =
 				width={media.width}
 				height={media.height}
 				loading={loading}
-				decoding="async"
+				fetchpriority={fetchpriority}
+				decoding={priority ? "sync" : "async"}
 				sizes={sizes}
 				class={className}
+				style={style}
 			/>
 		))
 }

package/components/Input.astro

@@ -0,0 +1,49 @@
+---
+/**
+ * Zone de saisie (`<input>` ou `<textarea>` avec `multiline`), classe `zef-input`. Avec `label`,
+ * elle est rendue dans un `<Field>` (libellé, aide, erreur). Les autres attributs sont passés
+ * tels quels (`name`, `type`, `required`, `placeholder`, `autocomplete`…).
+ */
+import type { HTMLAttributes } from "astro/types";
+import Field from "./Field.astro";
+
+type Props = Omit<HTMLAttributes<"input">, "class"> & {
+	label?: string;
+	help?: string;
+	error?: string;
+	multiline?: boolean;
+	rows?: number;
+	class?: string;
+};
+
+const {
+	label,
+	help,
+	error,
+	multiline = false,
+	rows = 5,
+	class: className,
+	id: givenId,
+	...rest
+} = Astro.props;
+const id =
+	givenId ?? (label ? `zef-${rest.name ?? Math.random().toString(36).slice(2, 8)}` : undefined);
+const attrs = {
+	...rest,
+	id,
+	class: `zef-input${className ? ` ${className}` : ""}`,
+	"aria-invalid": error ? "true" : undefined,
+};
+---
+
+{
+	label ? (
+		<Field label={label} for={id} help={help} error={error} required={Boolean(rest.required)}>
+			{multiline ? <textarea {...(attrs as HTMLAttributes<"textarea">)} rows={rows}>{rest.value ?? ""}</textarea> : <input {...attrs} />}
+		</Field>
+	) : multiline ? (
+		<textarea {...(attrs as HTMLAttributes<"textarea">)} rows={rows}>{rest.value ?? ""}</textarea>
+	) : (
+		<input {...attrs} />
+	)
+}

package/components/Popover.astro

@@ -0,0 +1,21 @@
+---
+/**
+ * Popover natif (attribut `popover`), sans JavaScript ni style imposé : ouvert par un bouton
+ * `<button popovertarget="<id>">`, fermé au clic en dehors et par Échap. Placé sous son bouton
+ * par le positionnement d'ancre CSS (`styles.css`), au centre de l'écran en repli.
+ * Classe `zef-popover` ; `manual` : ne se ferme pas au clic en dehors.
+ */
+interface Props {
+	id: string;
+	manual?: boolean;
+	/** Position par rapport au bouton : en dessous (défaut), au-dessus, à droite, à gauche. */
+	placement?: "bottom" | "top" | "right" | "left";
+	class?: string;
+}
+
+const { id, manual = false, placement = "bottom", class: className } = Astro.props;
+---
+
+<div id={id} popover={manual ? "manual" : "auto"} class:list={["zef-popover", className]} data-placement={placement}>
+	<slot />
+</div>

package/components/Select.astro

@@ -0,0 +1,55 @@
+---
+/**
+ * Liste déroulante native, classe `zef-select`. Options : `options` (`{ value: label }` ou
+ * `[{ value, label }]`) ou `<option>` en contenu. Avec `label`, rendue dans un `<Field>`.
+ */
+import type { HTMLAttributes } from "astro/types";
+import Field from "./Field.astro";
+
+type Option = { value: string; label: string };
+type Props = Omit<HTMLAttributes<"select">, "class"> & {
+	label?: string;
+	help?: string;
+	error?: string;
+	options?: Record<string, string> | Option[];
+	/** Première option vide (« Choisir… »). */
+	placeholder?: string;
+	value?: string;
+	class?: string;
+};
+
+const {
+	label,
+	help,
+	error,
+	options,
+	placeholder,
+	value,
+	class: className,
+	id: givenId,
+	...rest
+} = Astro.props;
+const id =
+	givenId ?? (label ? `zef-${rest.name ?? Math.random().toString(36).slice(2, 8)}` : undefined);
+const list: Option[] = Array.isArray(options)
+	? options
+	: Object.entries(options ?? {}).map(([v, l]) => ({ value: v, label: l }));
+---
+
+{
+	label ? (
+		<Field label={label} for={id} help={help} error={error} required={Boolean(rest.required)}>
+			<select {...rest} id={id} class:list={["zef-select", className]} aria-invalid={error ? "true" : undefined}>
+				{placeholder !== undefined && <option value="">{placeholder}</option>}
+				{list.map((o) => <option value={o.value} selected={o.value === value}>{o.label}</option>)}
+				<slot />
+			</select>
+		</Field>
+	) : (
+		<select {...rest} id={id} class:list={["zef-select", className]} aria-invalid={error ? "true" : undefined}>
+			{placeholder !== undefined && <option value="">{placeholder}</option>}
+			{list.map((o) => <option value={o.value} selected={o.value === value}>{o.label}</option>)}
+			<slot />
+		</select>
+	)
+}

package/components/Seo.astro

@@ -0,0 +1,24 @@
+---
+/**
+ * Référencement de la page (§ 5.13), à placer dans le `<head>` du gabarit :
+ * `<Seo {...Astro.props} organization={…} />`. Titre, description, robots, canonique, hreflang
+ * (avec `x-default`), Open Graph, Twitter et données structurées JSON-LD (WebSite, Organization
+ * ou LocalBusiness, WebPage, BreadcrumbList, Product pour la Boutique). Les champs viennent de
+ * l'onglet SEO de l'éditeur ; l'image de partage par défaut et l'adresse du site, du CMS.
+ */
+import { jsonLdScript, type SeoInput, seoTags } from "@agence-zef/astro";
+
+type Props = Omit<SeoInput, "url" | "origin"> & { url?: string };
+
+const props = Astro.props;
+const tags = seoTags({
+	...props,
+	url: props.url ?? Astro.url.pathname,
+	origin: Astro.site?.origin ?? Astro.url.origin,
+});
+---
+
+<title>{tags.title}</title>
+{tags.meta.map((m) => (m.name ? <meta name={m.name} content={m.content} /> : <meta property={m.property} content={m.content} />))}
+{tags.links.map((l) => <link rel={l.rel} href={l.href} hreflang={l.hreflang} />)}
+<script type="application/ld+json" is:inline set:html={jsonLdScript(tags.jsonLd)} />

package/components/routes/llms.ts

@@ -0,0 +1,24 @@
+import config from "virtual:zef/config";
+import { getClient, llmsTxt, siteOrigin, zefSiteIndex } from "@agence-zef/astro";
+import type { APIRoute } from "astro";
+
+/*
+ * `llms.txt` injecté par `@agence-zef/astro` (§ 5.13, format llmstxt.org) : le site présenté aux
+ * assistants IA, avec ses pages et ses collections et leur description.
+ */
+
+export const prerender = true;
+
+export const GET: APIRoute = async ({ site: astroSite }) => {
+	const site = await getClient().site();
+	const collections = (config.collections ?? [])
+		.filter((c) => c.page)
+		.map((c) => ({ name: c.name, label: c.label }));
+	const body = llmsTxt(
+		site,
+		await zefSiteIndex(config),
+		siteOrigin(site, astroSite?.origin),
+		collections,
+	);
+	return new Response(body, { headers: { "Content-Type": "text/plain; charset=utf-8" } });
+};

package/components/routes/page.astro

@@ -14,11 +14,22 @@ export async function getStaticPaths() {
 }
 
 const props = Astro.props as RouteProps;
-const { site, locale, title, alternates, header, footer } = props;
+const { site, locale, title, alternates, header, footer, url, breadcrumbs } = props;
 // Site en développement (§ 5.11) : aucune page n'est indexable.
 const seo = site.indexable === false ? { ...props.seo, noindex: true } : props.seo;
 ---
 
-<Layout site={site} locale={locale} title={title} seo={seo} alternates={alternates} header={header} footer={footer}>
+<Layout
+	site={site}
+	locale={locale}
+	title={title}
+	seo={seo}
+	alternates={alternates}
+	url={url}
+	breadcrumbs={breadcrumbs}
+	item={props.kind === "item" ? props.item : undefined}
+	header={header}
+	footer={footer}
+>
 	{props.kind === "page" ? <ZefSections sections={props.page.sections} /> : <ZefSections sections={props.item.sections ?? []} item={props.item} />}
 </Layout>

package/components/routes/robots.ts

@@ -1,16 +1,16 @@
-import { getClient } from "@agence-zef/astro";
+import { getClient, robotsTxt, siteOrigin } from "@agence-zef/astro";
 import type { APIRoute } from "astro";
 
 /*
- * `robots.txt` injecté par `@agence-zef/astro` (§ 5.11) : tout est bloqué tant que le site est en
- * développement ; une fois en ligne, les moteurs peuvent tout indexer. Construit avec le site :
- * la mise en ligne relance un build.
+ * `robots.txt` injecté par `@agence-zef/astro` (§ 5.11, § 5.13) : tout est bloqué tant que le site
+ * est en développement ; une fois en ligne, moteurs et assistants IA peuvent tout lire, le
+ * sitemap est déclaré. Construit avec le site : la mise en ligne relance un build.
  */
 
 export const prerender = true;
 
-export const GET: APIRoute = async () => {
+export const GET: APIRoute = async ({ site: astroSite }) => {
 	const site = await getClient().site();
-	const body = site.indexable ? "User-agent: *\nAllow: /\n" : "User-agent: *\nDisallow: /\n";
+	const body = robotsTxt(site, siteOrigin(site, astroSite?.origin));
 	return new Response(body, { headers: { "Content-Type": "text/plain; charset=utf-8" } });
 };

package/components/routes/sitemap.ts

@@ -0,0 +1,16 @@
+import config from "virtual:zef/config";
+import { getClient, sitemapXml, siteOrigin, zefSiteIndex } from "@agence-zef/astro";
+import type { APIRoute } from "astro";
+
+/*
+ * `sitemap.xml` injecté par `@agence-zef/astro` (§ 5.13) : pages et éléments publiés et
+ * indexables, chaque langue liée par `xhtml:link`, date de dernière publication.
+ */
+
+export const prerender = true;
+
+export const GET: APIRoute = async ({ site: astroSite }) => {
+	const site = await getClient().site();
+	const body = sitemapXml(await zefSiteIndex(config), siteOrigin(site, astroSite?.origin));
+	return new Response(body, { headers: { "Content-Type": "application/xml; charset=utf-8" } });
+};

package/dist/helpers.d.ts

@@ -23,12 +23,22 @@ export type LayoutProps = {
     seo: ApiSeo;
     /** Adresse dans chaque langue (sélecteur de langue, balises hreflang). */
     alternates: Record<string, string>;
+    /** Adresse de la page (`/la-cave`), base de la canonique et de `og:url`. */
+    url?: string;
+    /** Fil d'Ariane, de l'accueil à la page (données structurées BreadcrumbList). */
+    breadcrumbs?: Breadcrumb[];
+    /** Élément de collection affiché (données structurées : Product pour la Boutique). */
+    item?: ApiItem;
     /** Header et footer (sections partagées), à rendre avec `<ZefSections>` ; `null` sans `layout`. */
     header: ApiSection | null;
     footer: ApiSection | null;
     /** Aperçu de l'éditeur : à passer à `<ZefSections preview>` pour le header et le footer. */
     preview?: boolean;
 };
+export type Breadcrumb = {
+    title: string;
+    url: string;
+};
 export type RouteProps = LayoutProps & ({
     kind: "page";
     page: ApiPage;
@@ -46,13 +56,31 @@ export declare function zefLayoutProps(opts: {
     locale?: string;
     noindex?: boolean;
 }): Promise<LayoutProps>;
-/** Toutes les routes du site : pages publiées, puis éléments des collections avec page. */
+/**
+ * Toutes les routes du site : pages publiées, puis éléments des collections avec page. Calculé
+ * une fois par build : la route des pages, le sitemap et `llms.txt` partagent le résultat.
+ */
 export declare function zefStaticPaths(config: ZefConfig): Promise<{
     params: {
         path: string | undefined;
     };
     props: RouteProps;
 }[]>;
+/**
+ * Index du site pour le sitemap et `llms.txt` : une entrée par page et par élément avec page,
+ * dans chaque langue (titre, description, indexation, date de publication, langues).
+ */
+export declare function zefSiteIndex(config: ZefConfig): Promise<{
+    url: string;
+    locale: string;
+    title: string;
+    description: string | null;
+    noindex: boolean;
+    canonical: string | null;
+    updatedAt: string | null;
+    alternates: Record<string, string>;
+    collection: string | null;
+}[]>;
 /**
  * Origines du CMS autorisées à afficher l'aperçu : le sous-domaine du client (`ZEF_URL`) et
  * l'espace agence (`admin.` du même domaine), d'où l'agence gère ses clients.