@bapla/site-theme 0.0.0-stage → 0.2.0

package/dist/imgproxy-rioGvvyv.d.ts

@@ -0,0 +1,189 @@
+import * as react from 'react';
+import { ReactNode, ComponentType } from 'react';
+
+/**
+ * What the delivery API of Bapla Websites serves, as this package reads it.
+ * Field names follow the API (snake_case).
+ */
+type Shade = '50' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900' | '950';
+/** A colour ramp, `#rrggbb` per shade. */
+type Ramp = Record<Shade, string>;
+interface Font {
+    /** The Fontsource id, e.g. `inter`, `playfair-display`. */
+    id: string;
+    family: string;
+    fallback: 'sans-serif' | 'serif' | 'monospace';
+}
+type TypeLevel = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p';
+interface TypeStyle {
+    /** A CSS length, e.g. `2.5rem`. */
+    size: string;
+    weight: number;
+    line_height: number;
+    /** A CSS length, e.g. `-0.01em`. */
+    letter_spacing: string;
+}
+/** The site's Appearance configuration, defaults resolved by the API. */
+interface ResolvedAppearance {
+    mode: 'light' | 'dark' | 'both';
+    colors: {
+        primary: Ramp;
+        secondary: Ramp;
+        accent: Ramp;
+        neutral: Ramp;
+        background: string;
+        text: string;
+    };
+    fonts: {
+        body: Font;
+        heading: Font;
+    };
+    type: Record<TypeLevel, TypeStyle>;
+    /** A CSS length, e.g. `0.5rem`. */
+    radius: string;
+}
+/** A media as the delivery API serves it, on the site's own domain. */
+interface MediaValue {
+    id: string;
+    /** `/_media/web_med_…/name.jpg` */
+    url: string;
+    filename: string;
+    mime: string;
+    width: number | null;
+    height: number | null;
+    alt: string | null;
+    /** Fractions of the width and the height, 0 to 1. */
+    focal_point: {
+        x: number;
+        y: number;
+    } | null;
+}
+/** A `link` field's value. `url` may still be a node id the API did not resolve. */
+interface LinkValue {
+    url: string;
+    label: string | null;
+    new_tab: boolean;
+}
+/** A node of a blocks tree. */
+interface Block {
+    id: string;
+    type: string;
+    props?: Record<string, unknown>;
+    children?: Block[];
+}
+/** A ProseMirror node, as Tiptap writes it. */
+interface RichTextNode {
+    type: string;
+    attrs?: Record<string, unknown>;
+    marks?: {
+        type: string;
+        attrs?: Record<string, unknown>;
+    }[];
+    content?: RichTextNode[];
+    text?: string;
+}
+
+interface MediaTransform {
+    w?: number;
+    h?: number;
+    fit?: 'cover' | 'contain' | 'inside';
+    fm?: 'webp' | 'avif' | 'jpeg' | 'png';
+    /** Quality of a lossy format, 1 to 100 (80). */
+    q?: number;
+}
+/** The widths offered in a `srcset`. */
+declare const MEDIA_WIDTHS: number[];
+/**
+ * A media's address on the site's own domain, `/_media/<id>/<name>`, with
+ * the transformation asked for: the site relays it to the app, which reads
+ * the storage. No storage domain, no signed link in a page.
+ */
+declare function mediaUrl(media: Pick<MediaValue, 'id' | 'url' | 'filename'>, transform?: MediaTransform): string;
+/** A media field's value: the object the API expanded, or an id left to `resolve`. */
+declare function readMedia(value: unknown, resolve: (id: string) => MediaValue | null): MediaValue | null;
+/** The `object-position` of a focal point. */
+declare function objectPosition(focal: MediaValue['focal_point']): string | undefined;
+
+/** What a block component receives. */
+interface BlockProps<P extends Record<string, unknown> = Record<string, unknown>> {
+    block: Block;
+    props: P;
+    /** The block's children, rendered. */
+    children: ReactNode;
+    /** Renders a list of blocks with the same components: for a block that lays out its children itself. */
+    render: (blocks: Block[] | undefined) => ReactNode;
+}
+type BlockComponent = ComponentType<BlockProps<any>>;
+/** The interface's words. French by default; a site in another language passes its own. */
+interface ThemeLabels {
+    mainNavigation: string;
+    menu: string;
+    submenu: (label: string) => string;
+    breadcrumb: string;
+    carousel: string;
+    previous: string;
+    next: string;
+    slide: (index: number, count: number) => string;
+    goToSlide: (index: number) => string;
+    pause: string;
+    play: string;
+    embed: string;
+}
+declare const frenchLabels: ThemeLabels;
+/** A media's URL for a transform: `/_media?…` by default, the signed companion with `imgproxyUrls()`. */
+type ImageUrl = (media: MediaValue, transform?: MediaTransform) => string;
+/** A size by name (`card`), what `<Image size="card">` asks for. */
+interface ImageSize {
+    w?: number;
+    h?: number;
+    fit?: 'inside' | 'cover';
+    q?: number;
+}
+/** The sizes every site has; a site adds or replaces them with `imageSizes`. */
+declare const defaultImageSizes: Record<string, ImageSize>;
+interface SiteTheme {
+    /** Replacements and additions, by block type. */
+    components: Record<string, BlockComponent>;
+    /** A destination the API left as an id (`web_nod_…`): its path, or null to render the link inert. */
+    resolveLink: (url: string) => string | null;
+    /** A media the API left as an id (`web_med_…`). */
+    resolveMedia: (id: string) => MediaValue | null;
+    /** How an image's URL is built. */
+    imageUrl: ImageUrl;
+    /** Image sizes by name. */
+    imageSizes: Record<string, ImageSize>;
+    labels: ThemeLabels;
+}
+interface BlocksProviderProps {
+    components?: Record<string, BlockComponent>;
+    resolveLink?: SiteTheme['resolveLink'];
+    resolveMedia?: SiteTheme['resolveMedia'];
+    /** Signed URLs at the image companion: `imgproxyUrls()` of `@bapla/site-theme/server`. */
+    imageUrl?: ImageUrl;
+    /** Sizes added or replaced by name: `{ card: { w: 300, h: 300, fit: 'cover' } }`. */
+    imageSizes?: Record<string, ImageSize>;
+    labels?: Partial<ThemeLabels>;
+    children: ReactNode;
+}
+/**
+ * Replaces or adds block components, and says how ids are resolved. Nested
+ * providers add to the one above them.
+ */
+declare function BlocksProvider({ components, resolveLink, resolveMedia, imageUrl, imageSizes, labels, children }: BlocksProviderProps): react.JSX.Element;
+declare function useSiteTheme(): SiteTheme;
+
+/**
+ * The path of an image at the site's image companion (imgproxy on `/_img`,
+ * `features/websites.md` §5.9), before its signature:
+ * `/rs:fill:400:300:0/g:fp:0.5:0.3/q:80/plain/web_med_…/photo.jpg@webp`.
+ *
+ * The same translation as the app's `ImgproxyUrl`: `inside` is imgproxy's
+ * `fit`, `cover` its `fill` around the focal point; never enlarged; the
+ * source is the media's id and name, relative to the companion's origin.
+ * Signing needs the site's key: `imgproxyUrls()` of `@bapla/site-theme/server`.
+ */
+declare function imgproxyPath(media: Pick<MediaValue, 'id' | 'filename' | 'focal_point'>, transform?: MediaTransform): string;
+/** Images the companion transforms: not SVG, not GIF (animated), not video. */
+declare function isTransformable(media: Pick<MediaValue, 'mime'>): boolean;
+
+export { type Block as B, type Font as F, type ImageSize as I, type LinkValue as L, type MediaValue as M, type ResolvedAppearance as R, type Shade as S, type ThemeLabels as T, type BlockComponent as a, type BlockProps as b, BlocksProvider as c, type BlocksProviderProps as d, type ImageUrl as e, MEDIA_WIDTHS as f, type MediaTransform as g, type Ramp as h, type RichTextNode as i, type SiteTheme as j, type TypeLevel as k, type TypeStyle as l, defaultImageSizes as m, frenchLabels as n, imgproxyPath as o, isTransformable as p, mediaUrl as q, objectPosition as r, readMedia as s, useSiteTheme as u };

package/dist/index.d.ts

@@ -0,0 +1,220 @@
+import { B as Block, R as ResolvedAppearance, F as Font, a as BlockComponent, b as BlockProps, M as MediaValue, L as LinkValue } from './imgproxy-rioGvvyv.js';
+export { c as BlocksProvider, d as BlocksProviderProps, I as ImageSize, e as ImageUrl, f as MEDIA_WIDTHS, g as MediaTransform, h as Ramp, i as RichTextNode, S as Shade, j as SiteTheme, T as ThemeLabels, k as TypeLevel, l as TypeStyle, m as defaultImageSizes, n as frenchLabels, o as imgproxyPath, p as isTransformable, q as mediaUrl, r as objectPosition, s as readMedia, u as useSiteTheme } from './imgproxy-rioGvvyv.js';
+import * as react from 'react';
+import { CSSProperties, ReactNode } from 'react';
+
+/**
+ * A menu item, as the delivery API serves a menu (`features/websites.md`
+ * §5.8): the tree already resolved, disabled items gone, dynamic items
+ * already expanded — a labelled one as a heading over them, an unlabelled
+ * one in their place. Everything that depends on its shape reads it from
+ * here.
+ */
+interface MenuItem {
+    id: string;
+    kind: 'link' | 'heading' | 'panel';
+    label: string;
+    /** Null: a heading, a panel, or a link to a node no longer published (inert). */
+    url: string | null;
+    new_tab: boolean;
+    /** A link whose node is gone or unpublished — for an editor's preview. */
+    broken?: boolean;
+    /** The current page, or one of its ancestors. */
+    active?: boolean;
+    data: Record<string, unknown>;
+    /** `kind = panel` only: the blocks of the mega menu. */
+    panel: Block[] | null;
+    children: MenuItem[];
+}
+interface BreadcrumbItem {
+    label: string;
+    url: string | null;
+}
+
+/** The font stack: the variable build first (Fontsource names it `<Family> Variable`), then the static one. */
+declare function fontStack(font: Font): string;
+/**
+ * The stylesheet a site gets from its Appearance: a Tailwind CSS 4 `@theme`
+ * block — so `bg-primary-600`, `font-heading`, `text-h2` exist — and the
+ * base rules of the body, the headings and the paragraphs.
+ *
+ * Written into the site's CSS at build time, after `@import "tailwindcss"`.
+ */
+declare function themeCss(appearance: ResolvedAppearance): string;
+/**
+ * The font packages a site imports at build time: fonts are self-hosted,
+ * never fetched from Google Fonts or a CDN by the page.
+ *
+ * Variable builds by default (`@fontsource-variable/<id>`); with
+ * `variable: false`, the static weights the Appearance uses
+ * (`@fontsource/<id>/<weight>.css`).
+ */
+declare function fontImports(appearance: ResolvedAppearance, options?: {
+    variable?: boolean;
+}): string[];
+
+/**
+ * A blocks tree, `{id, type, props, children}`, rendered with the standard
+ * components and those the provider adds. A type nobody renders renders
+ * nothing: content written for a theme's block does not break another theme.
+ */
+declare function Blocks({ blocks }: {
+    blocks: Block[] | null | undefined;
+}): react.JSX.Element;
+
+/**
+ * The standard blocks of `websites` (`BlockCatalog`), by type. A theme
+ * replaces one, or adds its own, through `BlocksProvider`.
+ */
+declare const standardBlocks: Record<string, BlockComponent>;
+
+declare function Section({ props, children }: BlockProps): react.JSX.Element;
+/**
+ * Three modes: `equal` (as many equal columns as `columns`), `auto` (as
+ * many as fit `min_width`), `custom` (each column its `width`, in twelfths
+ * or in percent). Stacked into one column below `stack_below`.
+ *
+ * The layout is set through custom properties, so a media query of
+ * `base.css` can stack it and a theme can override it with a class.
+ */
+declare function Grid({ block, props, children }: BlockProps): react.JSX.Element;
+declare function Column({ props, children }: BlockProps): react.JSX.Element;
+declare function Divider({ props }: BlockProps): react.JSX.Element;
+declare function Spacer({ props }: BlockProps): react.JSX.Element;
+
+declare function Text({ props }: BlockProps): react.JSX.Element;
+declare function MediaBlock({ props }: BlockProps): react.JSX.Element | null;
+declare function Button({ props }: BlockProps): react.JSX.Element | null;
+/** The player address of a known service, or null: an unknown address is shown as a link, never framed. */
+declare function embedUrl(address: string): string | null;
+declare function Embed({ props }: BlockProps): react.JSX.Element | null;
+
+/**
+ * Slides, one child block each (WAI-ARIA carousel pattern): arrows and dots
+ * are buttons, the arrow keys move, autoplay stops on hover, on focus, on
+ * its pause button, and never starts when motion is reduced.
+ */
+declare function Carousel({ block, props, render }: BlockProps): react.JSX.Element | null;
+/**
+ * Tabs (WAI-ARIA tabs pattern, automatic activation): one tab stop, the
+ * arrow keys move between tabs, Home and End go to the ends.
+ */
+declare function Tabs({ block, props, render }: BlockProps): react.JSX.Element | null;
+/** Panels that fold (WAI-ARIA accordion pattern): each header is a button. */
+declare function Accordion({ block, props, render }: BlockProps): react.JSX.Element;
+
+/**
+ * A rich text field, from its ProseMirror JSON — the nodes and marks of
+ * the presets the API accepts. No Tiptap on the site, no HTML string: an
+ * unknown node renders its content, or nothing.
+ */
+declare function RichText({ doc, className }: {
+    doc: unknown;
+    className?: string;
+}): react.JSX.Element | null;
+
+interface MediaProps {
+    media: MediaValue;
+    /** Replaces the media's own alternative text. An empty string marks it decorative. */
+    alt?: string | null;
+    /** The `sizes` of the `srcset`. */
+    sizes?: string;
+    /** Crops to the box (`object-fit: cover`) around the focal point. */
+    cover?: boolean;
+    /** Above the fold: loaded eagerly. */
+    priority?: boolean;
+    className?: string;
+    style?: CSSProperties;
+}
+/** An image with its `srcset` (the theme's `imageUrl`: the companion, or `/_media`), or a video. */
+declare function Media({ media, alt, sizes, cover, priority, className, style }: MediaProps): react.JSX.Element;
+
+type Format = 'avif' | 'webp';
+interface ImageProps {
+    media: MediaValue;
+    /** A size by name — `card`, `thumbnail`, or one of the site's `imageSizes`. */
+    size?: string;
+    /** The box, in CSS pixels; with `size`, replaces its value. */
+    w?: number;
+    h?: number;
+    /** `inside` (the whole image in the box) or `cover` (the box filled, cropped around the focal point). */
+    fit?: 'inside' | 'cover';
+    q?: number;
+    /** Replaces the media's own alternative text; an empty string marks it decorative. */
+    alt?: string | null;
+    /**
+     * Responsive widths: a `srcset` in `w` descriptors, with `sizes`. Without
+     * them, the image is the box at 1x and 2x.
+     */
+    widths?: number[];
+    sizes?: string;
+    /** A `<picture>` with a source per modern format, the `<img>` in the source's own as a fallback. */
+    formats?: Format[];
+    /** Above the fold: loaded eagerly, fetched first. */
+    priority?: boolean;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * An image at the size asked for: by name (`<Image media={m} size="card" />`)
+ * or by its box (`w`, `h`, `fit`), in an `<img>` with 1x/2x or responsive
+ * widths, or a `<picture>` with AVIF and WebP sources. Its URLs are the
+ * theme's: signed at the image companion when the site has one
+ * (`imgproxyUrls()`), `/_media?w=…` otherwise. Never enlarged: the
+ * candidates stop at the source's size.
+ */
+declare function Image({ media, size, w, h, fit, q, alt, widths, sizes, formats, priority, className, style }: ImageProps): react.JSX.Element;
+
+/**
+ * The `href` of a destination, or null when it must not be followed: what
+ * the API accepts (a path, an anchor, `mailto:`, `tel:`, `http(s)`), checked
+ * again here; a node id goes through `resolve`.
+ */
+declare function safeHref(url: unknown, resolve?: (url: string) => string | null): string | null;
+/** A `link` field's value, read loosely: the API sends an object, older content may hold a string. */
+declare function readLink(value: unknown): LinkValue | null;
+/** The attributes of an anchor that opens in a new tab. */
+declare function targetProps(newTab: boolean): {
+    target?: string;
+    rel?: string;
+};
+
+interface NavBarProps {
+    items: MenuItem[];
+    /** The `aria-label` of the `<nav>`; « Navigation principale » by default. */
+    label?: string;
+    /** Before the list: the site's logo and name, as a link home. */
+    brand?: ReactNode;
+    className?: string;
+}
+/**
+ * The site's navigation bar (disclosure navigation pattern, not an ARIA
+ * menu): links are links, an item with children has a button that shows
+ * them, Escape closes and gives the focus back, leaving the bar closes
+ * everything. A `panel` item opens a mega menu, its blocks rendered with the
+ * item in context (`menu_links`). Below the `md` width, the list folds
+ * behind a « Menu » button.
+ */
+declare function NavBar({ items, label, brand, className }: NavBarProps): react.JSX.Element;
+
+/** The trail to the current page, the last item being it. */
+declare function Breadcrumb({ items, className }: {
+    items: BreadcrumbItem[];
+    className?: string;
+}): react.JSX.Element | null;
+
+declare function MenuItemLink({ item, className }: {
+    item: MenuItem;
+    className?: string;
+}): react.JSX.Element;
+/**
+ * In a mega menu's panel: the links under the panel's item — or under one
+ * of its descendants, named by `item` — two levels deep.
+ */
+declare function MenuLinks({ props }: BlockProps): react.JSX.Element | null;
+
+/** The menu item whose panel is being rendered: what `menu_links` lists. */
+declare const MenuItemContext: react.Context<MenuItem | null>;
+declare function useMenuItem(): MenuItem | null;
+
+export { Accordion, Block, BlockComponent, BlockProps, Blocks, Breadcrumb, type BreadcrumbItem, Button, Carousel, Column, Divider, Embed, Font, Grid, Image, type ImageProps, LinkValue, Media, MediaBlock, type MediaProps, MediaValue, type MenuItem, MenuItemContext, MenuItemLink, MenuLinks, NavBar, type NavBarProps, ResolvedAppearance, RichText, Section, Spacer, Tabs, Text, embedUrl, fontImports, fontStack, readLink, safeHref, standardBlocks, targetProps, themeCss, useMenuItem };