@goldencomm/create-baseline 0.0.1 → 0.1.0

package/templates/wordpress/theme/inc/components/avatar.php

@@ -0,0 +1,111 @@
+<?php
+/**
+ * Baseline Avatar for template code (spec: components/avatar/spec.md): a person or entity that is not a WordPress user
+ * (a team member, a testimonial author, a company). Post and comment authors use core/avatar, styled in
+ * src/core-avatar.css. Emits the same markup and classes as the React Avatar (registry/src/ui/avatar/avatar.tsx):
+ *
+ *   echo baseline_avatar(['src' => $photo_url, 'alt' => 'Jordan Diaz', 'fallback' => 'JD']);
+ *   echo baseline_avatar(['fallback' => 'JD', 'size' => 'lg', 'badge' => 'success', 'badge_label' => 'online']);
+ *   echo baseline_avatar(['icon' => 'user', 'size' => 'sm']);
+ *
+ * Without JavaScript there is no load state: the <img> renders when there is a URL and the fallback otherwise.
+ * Class strings are static maps (ADR-0008): Tailwind scans this file, so every class must appear here literally.
+ */
+
+declare(strict_types=1);
+
+const BASELINE_AVATAR_ROOT = 'group/avatar relative flex shrink-0 rounded-full select-none after:pointer-events-none after:absolute after:inset-0 after:rounded-full after:border-(length:--bl-avatar-border-width) after:border-border after:mix-blend-darken';
+
+const BASELINE_AVATAR_SIZES = [
+    'xs' => 'size-(--bl-avatar-xs-size)',
+    'sm' => 'size-(--bl-avatar-sm-size)',
+    'md' => 'size-(--bl-avatar-md-size)',
+    'lg' => 'size-(--bl-avatar-lg-size)',
+    'xl' => 'size-(--bl-avatar-xl-size)',
+];
+
+const BASELINE_AVATAR_IMAGE = 'aspect-square size-full rounded-full object-cover';
+
+const BASELINE_AVATAR_FALLBACK = 'flex size-full items-center justify-center rounded-full bg-muted text-muted-foreground font-(family-name:--bl-avatar-font-family) font-(--bl-avatar-font-weight) group-data-[size=xs]/avatar:text-(length:--bl-avatar-xs-font-size) group-data-[size=xs]/avatar:leading-(--bl-avatar-xs-line-height) group-data-[size=sm]/avatar:text-(length:--bl-avatar-sm-font-size) group-data-[size=sm]/avatar:leading-(--bl-avatar-sm-line-height) group-data-[size=md]/avatar:text-(length:--bl-avatar-md-font-size) group-data-[size=md]/avatar:leading-(--bl-avatar-md-line-height) group-data-[size=lg]/avatar:text-(length:--bl-avatar-lg-font-size) group-data-[size=lg]/avatar:leading-(--bl-avatar-lg-line-height) group-data-[size=xl]/avatar:text-(length:--bl-avatar-xl-font-size) group-data-[size=xl]/avatar:leading-(--bl-avatar-xl-line-height)';
+
+// the fallback icon's size per avatar size (an svg here, where React sizes its <Icon> span)
+const BASELINE_AVATAR_ICON = [
+    'xs' => 'size-(--bl-avatar-xs-icon-size)',
+    'sm' => 'size-(--bl-avatar-sm-icon-size)',
+    'md' => 'size-(--bl-avatar-md-icon-size)',
+    'lg' => 'size-(--bl-avatar-lg-icon-size)',
+    'xl' => 'size-(--bl-avatar-xl-icon-size)',
+];
+
+const BASELINE_AVATAR_BADGE = 'absolute end-0 bottom-0 z-10 inline-flex items-center justify-center rounded-full bg-primary text-primary-foreground select-none ring-(length:--bl-overlap-ring-width) ring-background group-data-[size=xs]/avatar:size-(--bl-avatar-xs-badge-size) group-data-[size=sm]/avatar:size-(--bl-avatar-sm-badge-size) group-data-[size=md]/avatar:size-(--bl-avatar-md-badge-size) group-data-[size=lg]/avatar:size-(--bl-avatar-lg-badge-size) group-data-[size=xl]/avatar:size-(--bl-avatar-xl-badge-size)';
+
+/**
+ * @param array{
+ *   src?: string, alt?: string, fallback?: string, icon?: string, size?: string,
+ *   badge?: bool|string, badge_label?: string, class?: string, root_attrs?: string
+ * } $args `badge` is true for a plain dot or a status scheme ('success' | 'warning' | 'error'); `root_attrs` replaces
+ *   the root's class attribute (the acf/avatar block passes get_block_wrapper_attributes() built on
+ *   baseline_avatar_classes(), so the avatar itself is the block's root and no wrapper div breaks a group)
+ */
+function baseline_avatar(array $args): string
+{
+    $size = baseline_avatar_size((string) ($args['size'] ?? 'md'));
+    $src = (string) ($args['src'] ?? '');
+    $alt = (string) ($args['alt'] ?? '');
+
+    if ($src !== '') {
+        $inner = '<img data-slot="avatar-image" class="' . BASELINE_AVATAR_IMAGE . '" src="' . esc_url($src) . '" alt="' . esc_attr($alt) . '" loading="lazy" decoding="async">';
+    } else {
+        $content = !empty($args['icon'])
+            ? baseline_icon((string) $args['icon'], BASELINE_AVATAR_ICON[$size] . ' shrink-0', $alt)
+            : esc_html((string) ($args['fallback'] ?? ''));
+        $label = ($alt !== '' && empty($args['icon'])) ? ' role="img" aria-label="' . esc_attr($alt) . '"' : '';
+        $inner = '<span data-slot="avatar-fallback" class="' . BASELINE_AVATAR_FALLBACK . '"' . $label . '>' . $content . '</span>';
+    }
+
+    $badge = '';
+    if (!empty($args['badge'])) {
+        $scheme = in_array($args['badge'], ['success', 'warning', 'error'], true) ? ' data-scheme="' . $args['badge'] . '"' : '';
+        $hidden = !empty($args['badge_label']) ? '<span class="sr-only">' . esc_html((string) $args['badge_label']) . '</span>' : '';
+        $badge  = '<span data-slot="avatar-badge" class="' . BASELINE_AVATAR_BADGE . '"' . $scheme . '>' . $hidden . '</span>';
+    }
+
+    $root = isset($args['root_attrs'])
+        ? (string) $args['root_attrs']
+        : 'class="' . esc_attr(baseline_avatar_classes($size, (string) ($args['class'] ?? ''))) . '"';
+    return '<span data-slot="avatar" data-size="' . $size . '" ' . $root . '>' . $inner . $badge . '</span>';
+}
+
+/** A size from the five, md otherwise. */
+function baseline_avatar_size(string $size): string
+{
+    return isset(BASELINE_AVATAR_SIZES[$size]) ? $size : 'md';
+}
+
+/** The avatar root's classes for a size (shared by baseline_avatar() and the acf/avatar block's wrapper attributes). */
+function baseline_avatar_classes(string $size, string $extra = ''): string
+{
+    // not-typeset: typeset's media rule gives an <img> a top margin and radius, which pushed the photo out of the circle
+    return trim(BASELINE_AVATAR_ROOT . ' not-typeset ' . BASELINE_AVATAR_SIZES[baseline_avatar_size($size)] . ' ' . $extra);
+}
+
+// Avatar Group and its "+N" count: the React AvatarGroup / AvatarGroupCount classes (each avatar after the first moves
+// in by avatar/group/gap and gets the shared overlap ring; the count takes the size of the group's avatars).
+const BASELINE_AVATAR_GROUP = 'group/avatar-group not-typeset flex space-x-(--bl-avatar-group-gap) *:data-[slot=avatar]:ring-(length:--bl-overlap-ring-width) *:data-[slot=avatar]:ring-background';
+
+const BASELINE_AVATAR_GROUP_COUNT = 'after:pointer-events-none after:absolute after:inset-0 after:rounded-full after:border-(length:--bl-avatar-border-width) after:border-border after:mix-blend-darken relative flex shrink-0 items-center justify-center rounded-full bg-muted text-muted-foreground ring-(length:--bl-overlap-ring-width) ring-background font-(family-name:--bl-avatar-font-family) font-(--bl-avatar-font-weight) size-(--bl-avatar-md-size) text-(length:--bl-avatar-md-font-size) leading-(--bl-avatar-md-line-height) group-has-data-[size=xs]/avatar-group:size-(--bl-avatar-xs-size) group-has-data-[size=xs]/avatar-group:text-(length:--bl-avatar-xs-font-size) group-has-data-[size=xs]/avatar-group:leading-(--bl-avatar-xs-line-height) group-has-data-[size=sm]/avatar-group:size-(--bl-avatar-sm-size) group-has-data-[size=sm]/avatar-group:text-(length:--bl-avatar-sm-font-size) group-has-data-[size=sm]/avatar-group:leading-(--bl-avatar-sm-line-height) group-has-data-[size=lg]/avatar-group:size-(--bl-avatar-lg-size) group-has-data-[size=lg]/avatar-group:text-(length:--bl-avatar-lg-font-size) group-has-data-[size=lg]/avatar-group:leading-(--bl-avatar-lg-line-height) group-has-data-[size=xl]/avatar-group:size-(--bl-avatar-xl-size) group-has-data-[size=xl]/avatar-group:text-(length:--bl-avatar-xl-font-size) group-has-data-[size=xl]/avatar-group:leading-(--bl-avatar-xl-line-height)';
+
+/** The "+N" that ends a group. */
+function baseline_avatar_group_count(int $count): string
+{
+    return '<div data-slot="avatar-group-count" class="' . BASELINE_AVATAR_GROUP_COUNT . '">+' . $count . '</div>';
+}
+
+/** The acf/avatar block's Icon select lists the active icon set's vocabulary, as acf/badge's does. */
+add_filter('acf/load_field/key=field_baseline_avatar_icon', static function (array $field): array {
+    $field['choices'] = ['' => __('None (initials)', 'baseline')];
+    foreach (baseline_icons() as $name => $icon) {
+        $field['choices'][$name] = (string) ($icon['label'] ?? $name);
+    }
+    return $field;
+});

package/templates/wordpress/theme/inc/components/badge.php

@@ -0,0 +1,96 @@
+<?php
+/**
+ * Baseline Badge for template code and the acf/badge block (spec: components/badge/spec.md). Emits the same markup
+ * and classes as the React Badge (registry/src/ui/badge/badge.tsx), so the HTML target and this theme agree:
+ *
+ *   echo baseline_badge(['label' => 'New']);
+ *   echo baseline_badge(['label' => 'Sale', 'variant' => 'destructive', 'size' => 'sm']);
+ *   echo baseline_badge(['label' => 'Paid', 'scheme' => 'success', 'icon' => 'check']);
+ *   echo baseline_badge(['label' => 'Docs', 'variant' => 'outline', 'href' => '/docs']);
+ *
+ * Status is the scheme, never a variant (PLAN §5.2): `scheme` renders as data-scheme on the badge.
+ * Class strings are static maps (ADR-0008): Tailwind scans this file, so every class must appear here literally.
+ */
+
+declare(strict_types=1);
+
+const BASELINE_BADGE_BASE = 'group/badge inline-flex w-fit shrink-0 items-center justify-center overflow-hidden whitespace-nowrap border-(length:--bl-badge-border-width) border-transparent font-(--bl-badge-font-weight) transition-all focus-visible:border-ring focus-visible:ring-(length:--bl-control-ring-width) focus-visible:ring-ring/50 [&>svg]:pointer-events-none';
+
+const BASELINE_BADGE_VARIANTS = [
+    'default'     => 'bg-primary text-primary-foreground [a]:hover:bg-primary/80',
+    'secondary'   => 'bg-secondary text-secondary-foreground [a]:hover:bg-secondary/80',
+    'destructive' => 'bg-destructive/10 text-destructive focus-visible:ring-destructive/20 [a]:hover:bg-destructive/20',
+    'outline'     => 'border-border text-foreground [a]:hover:bg-muted [a]:hover:text-muted-foreground',
+    'ghost'       => 'text-foreground [a]:hover:bg-muted [a]:hover:text-muted-foreground',
+    'link'        => 'text-primary underline-offset-4 [a]:hover:underline',
+];
+
+const BASELINE_BADGE_SIZES = [
+    'sm' => 'h-(--bl-badge-sm-height) gap-(--bl-badge-sm-gap) px-(--bl-badge-sm-padding-x) rounded-(--bl-badge-sm-radius) text-(length:--bl-badge-sm-font-size) leading-(--bl-badge-sm-line-height) [&>svg]:size-(--bl-badge-sm-icon-size) has-data-[icon=inline-start]:ps-(--bl-badge-sm-padding-x-icon) has-data-[icon=inline-end]:pe-(--bl-badge-sm-padding-x-icon)',
+    'md' => 'h-(--bl-badge-md-height) gap-(--bl-badge-md-gap) px-(--bl-badge-md-padding-x) rounded-(--bl-badge-md-radius) text-(length:--bl-badge-md-font-size) leading-(--bl-badge-md-line-height) [&>svg]:size-(--bl-badge-md-icon-size) has-data-[icon=inline-start]:ps-(--bl-badge-md-padding-x-icon) has-data-[icon=inline-end]:pe-(--bl-badge-md-padding-x-icon)',
+];
+
+const BASELINE_BADGE_SCHEMES = ['success', 'warning', 'error'];
+
+/**
+ * @param array{
+ *   label?: string, variant?: string, size?: string, scheme?: string, icon?: string, icon_position?: string,
+ *   href?: string, target?: string, class?: string
+ * } $args
+ */
+function baseline_badge(array $args): string
+{
+    $variant = (string) ($args['variant'] ?? 'default');
+    $size    = (string) ($args['size'] ?? 'md');
+    $scheme  = (string) ($args['scheme'] ?? '');
+    $icon    = (string) ($args['icon'] ?? '');
+    $end     = ($args['icon_position'] ?? 'start') === 'end';
+    $href    = (string) ($args['href'] ?? '');
+    if (!isset(BASELINE_BADGE_VARIANTS[$variant])) {
+        $variant = 'default';
+    }
+    if (!isset(BASELINE_BADGE_SIZES[$size])) {
+        $size = 'md';
+    }
+
+    // not-typeset: a link badge in post content must not take typeset's link styling (ADR-0028)
+    $classes = trim(BASELINE_BADGE_BASE . ' not-typeset ' . BASELINE_BADGE_VARIANTS[$variant] . ' ' . BASELINE_BADGE_SIZES[$size] . ' ' . (string) ($args['class'] ?? ''));
+    $attrs = [
+        'class'        => $classes,
+        'data-slot'    => 'badge',
+        'data-variant' => $variant,
+        'data-size'    => $size,
+        'data-scheme'  => in_array($scheme, BASELINE_BADGE_SCHEMES, true) ? $scheme : null,
+    ];
+
+    $glyph = '';
+    if ($icon !== '') {
+        // shrink-0 only: the badge's [&>svg]:size-* rule sizes the glyph from the tokens
+        $svg   = baseline_icon($icon, 'shrink-0');
+        $glyph = (string) preg_replace('/^<svg\b/', '<svg data-icon="' . ($end ? 'inline-end' : 'inline-start') . '"', $svg, 1);
+    }
+    $label = esc_html((string) ($args['label'] ?? __('Badge', 'baseline')));
+    $inner = $end ? $label . $glyph : $glyph . $label;
+
+    if ($href !== '') {
+        $attrs['href'] = $href;
+        if (!empty($args['target'])) {
+            $attrs['target'] = (string) $args['target'];
+            $attrs['rel']    = 'noopener';
+        }
+        return '<a' . baseline_attrs($attrs) . '>' . $inner . '</a>';
+    }
+    return '<span' . baseline_attrs($attrs) . '>' . $inner . '</span>';
+}
+
+/**
+ * The block's Icon select lists the active icon set's vocabulary (inc/icons.generated.php), so it follows the set
+ * the designer picked in Figma with nothing hand-kept.
+ */
+add_filter('acf/load_field/key=field_baseline_badge_icon', static function (array $field): array {
+    $field['choices'] = ['' => __('None', 'baseline')];
+    foreach (baseline_icons() as $name => $icon) {
+        $field['choices'][$name] = (string) ($icon['label'] ?? $name);
+    }
+    return $field;
+});

package/templates/wordpress/theme/inc/components/button.php

@@ -0,0 +1,77 @@
+<?php
+/**
+ * Baseline Button for template code (header phone link, templates, other blocks). Emits the SAME markup and classes
+ * as core/button (ADR-0018), so one stylesheet serves editors and templates:
+ *
+ *   echo baseline_button(['label' => 'Call us', 'href' => 'tel:+15555555555', 'variant' => 'outline', 'size' => 'sm']);
+ *   echo baseline_button(['label' => 'Add to cart', 'type' => 'submit', 'disabled' => !$in_stock]);
+ *
+ * Spec: components/button/spec.md. Icon-only sizes arrive with the icon vocabulary (M5).
+ */
+
+declare(strict_types=1);
+
+/**
+ * @param array{
+ *   label?: string, href?: string, target?: string, type?: string, variant?: string, size?: string,
+ *   disabled?: bool, id?: string, class?: string, attrs?: array<string, string|bool|null>, children?: string
+ * } $args
+ */
+function baseline_button(array $args): string
+{
+    $label    = (string) ($args['label'] ?? 'Button');
+    $href     = (string) ($args['href'] ?? '');
+    $variant  = (string) ($args['variant'] ?? 'default');
+    $size     = (string) ($args['size'] ?? 'md');
+    $disabled = (bool) ($args['disabled'] ?? false);
+    if (!isset(BASELINE_BUTTON_STYLES[$variant])) {
+        $variant = 'default';
+    }
+    if (!in_array($size, BASELINE_BUTTON_SIZES, true)) {
+        $size = 'md';
+    }
+
+    $wrapper = trim('wp-block-button is-style-' . BASELINE_BUTTON_STYLES[$variant] . ' is-size-' . $size . ' ' . (string) ($args['class'] ?? ''));
+    $attrs = [
+        'class'        => 'wp-block-button__link wp-element-button',
+        'data-variant' => $variant,
+        'data-size'    => $size,
+        'id'           => $args['id'] ?? null,
+    ];
+    foreach ((array) ($args['attrs'] ?? []) as $k => $v) {
+        $attrs[$k] = $v;
+    }
+    $inner = isset($args['children']) ? (string) $args['children'] : esc_html($label);
+
+    if ($href !== '' && !$disabled) {
+        $attrs['href'] = $href;
+        if (!empty($args['target'])) {
+            $attrs['target'] = (string) $args['target'];
+            $attrs['rel']    = 'noopener';
+        }
+        $el = '<a' . baseline_attrs($attrs) . '>' . $inner . '</a>';
+    } else {
+        $attrs['type'] = (string) ($args['type'] ?? 'button');
+        if ($disabled) {
+            $attrs['disabled']      = true;
+            $attrs['aria-disabled'] = 'true';
+        }
+        $el = '<button' . baseline_attrs($attrs) . '>' . $inner . '</button>';
+    }
+    return '<div class="' . esc_attr($wrapper) . '">' . $el . '</div>';
+}
+
+/** Escapes and joins an attribute map; true renders a bare attribute, null/false/'' omit it. */
+function baseline_attrs(array $attrs): string
+{
+    $out = '';
+    foreach ($attrs as $k => $v) {
+        if ($v === null || $v === false || $v === '') {
+            continue;
+        }
+        $out .= $v === true
+            ? ' ' . esc_attr((string) $k)
+            : ' ' . esc_attr((string) $k) . '="' . ($k === 'href' ? esc_url((string) $v) : esc_attr((string) $v)) . '"';
+    }
+    return $out;
+}

package/templates/wordpress/theme/inc/components/dialog.php

@@ -0,0 +1,98 @@
+<?php
+/**
+ * Baseline Dialog for template code and the acf/dialog block (spec: components/dialog/spec.md). Emits the same markup
+ * and classes as the React Dialog (registry/src/ui/dialog/dialog.tsx): a native <dialog closedby="any"> opened by a
+ * Button carrying command="show-modal" commandfor, so it works with no JavaScript (ladder 1):
+ *
+ *   echo baseline_dialog([
+ *       'id' => 'newsletter', 'trigger' => 'Subscribe', 'title' => 'Join the newsletter',
+ *       'description' => 'One email a month.', 'body' => $form_html, 'footer' => baseline_dialog_footer('', true),
+ *   ]);
+ *
+ * Safari has no `closedby` yet (2026-10), so there an outside click does not close it; Escape and the buttons do.
+ * Class strings are static (ADR-0008) and kept identical to React's, so one look serves both.
+ */
+
+declare(strict_types=1);
+
+// The <dialog> (React's contentClasses, minus the full-bleed media rule, which has no WordPress counterpart yet).
+const BASELINE_DIALOG_CONTENT = 'group/dialog-content fixed inset-0 m-auto h-fit max-h-[calc(100%-2rem)] w-full max-w-[calc(100%-2rem)] sm:max-w-(--bl-dialog-max-width) hidden open:grid gap-(--bl-dialog-gap) overflow-y-auto overscroll-contain rounded-(--bl-dialog-radius) border-0 bg-popover p-(--bl-dialog-padding) text-sm text-popover-foreground outline-none ring-(length:--bl-dialog-border-width) ring-(--bl-dialog-border) scale-95 opacity-0 open:scale-100 open:opacity-100 starting:open:scale-95 starting:open:opacity-0 transition-[opacity,scale,display,overlay] transition-discrete duration-100 motion-reduce:transition-none backdrop:bg-(--overlay) supports-backdrop-filter:backdrop:backdrop-blur-xs backdrop:opacity-0 open:backdrop:opacity-100 starting:open:backdrop:opacity-0 backdrop:transition-[opacity,display,overlay] backdrop:transition-discrete backdrop:duration-100 motion-reduce:backdrop:transition-none';
+
+// The block editor shows the panel in place (a closed <dialog> would hide the content editors need to reach).
+const BASELINE_DIALOG_PREVIEW = 'relative grid w-full max-w-(--bl-dialog-max-width) gap-(--bl-dialog-gap) rounded-(--bl-dialog-radius) bg-popover p-(--bl-dialog-padding) text-sm text-popover-foreground ring-(length:--bl-dialog-border-width) ring-(--bl-dialog-border)';
+
+const BASELINE_DIALOG_HEADER = 'flex flex-col gap-(--bl-dialog-header-gap)';
+const BASELINE_DIALOG_TITLE = 'm-0 font-heading text-(length:--bl-dialog-title-font-size) leading-(--bl-dialog-title-line-height) font-(--bl-dialog-title-font-weight)';
+const BASELINE_DIALOG_DESCRIPTION = 'm-0 text-(length:--bl-dialog-description-font-size) leading-(--bl-dialog-description-line-height) text-muted-foreground *:[a]:underline *:[a]:underline-offset-3 *:[a]:hover:text-foreground';
+const BASELINE_DIALOG_FOOTER = '-mx-(--bl-dialog-padding) -mb-(--bl-dialog-padding) flex flex-col-reverse gap-(--bl-dialog-footer-gap) sm:flex-row sm:justify-end rounded-b-(--bl-dialog-radius) border-t-(length:--bl-dialog-border-width) border-border bg-(--bl-dialog-footer-background) p-(--bl-dialog-padding)';
+const BASELINE_DIALOG_CLOSE = 'absolute top-(--bl-dialog-close-inset) end-(--bl-dialog-close-inset)';
+
+/**
+ * The footer: bordered and muted, bleeding to the dialog's edges, stacked below sm. `$close_label` adds an outline
+ * button that closes the dialog through <form method="dialog">, which needs no id and no script.
+ */
+function baseline_dialog_footer(string $actions, string $close_label = '', string $root_attrs = ''): string
+{
+    $close = '';
+    if ($close_label !== '') {
+        $close = '<form method="dialog" class="contents">'
+            . baseline_button(['label' => $close_label, 'variant' => 'outline', 'type' => 'submit'])
+            . '</form>';
+    }
+    $root = $root_attrs !== '' ? $root_attrs : 'class="' . esc_attr(BASELINE_DIALOG_FOOTER) . '"';
+    // Close first: it is the Cancel beside the primary action, so the row reads Cancel, Continue (upstream's demo order)
+    // and the stacked footer (flex-col-reverse) puts the primary action on top.
+    return '<div data-slot="dialog-footer" ' . $root . '>' . $close . $actions . '</div>';
+}
+
+/**
+ * @param array{
+ *   id?: string, trigger?: string|false, trigger_variant?: string, class?: string, trigger_size?: string, title?: string,
+ *   description?: string, body?: string, footer?: string, show_close?: bool, preview?: bool
+ * } $args `body` and `footer` are ready markup (InnerBlocks, a form, baseline_dialog_footer()); `preview` renders the
+ *   panel in place, for the block editor. `trigger` false leaves the trigger out, for a dialog opened another way (Media's
+ *   play button); `class` adds classes to the <dialog>.
+ */
+function baseline_dialog(array $args): string
+{
+    $id      = sanitize_html_class((string) ($args['id'] ?? '')) ?: wp_unique_id('dialog-');
+    $title   = (string) ($args['title'] ?? '');
+    $desc    = (string) ($args['description'] ?? '');
+    $preview = !empty($args['preview']);
+
+    $header = '';
+    if ($title !== '' || $desc !== '') {
+        $header = '<div data-slot="dialog-header" class="' . BASELINE_DIALOG_HEADER . '">'
+            . ($title !== '' ? '<h2 id="' . esc_attr($id . '-title') . '" data-slot="dialog-title" class="' . BASELINE_DIALOG_TITLE . '">' . esc_html($title) . '</h2>' : '')
+            . ($desc !== '' ? '<p id="' . esc_attr($id . '-description') . '" data-slot="dialog-description" class="' . BASELINE_DIALOG_DESCRIPTION . '">' . esc_html($desc) . '</p>' : '')
+            . '</div>';
+    }
+
+    $close = '';
+    if ($args['show_close'] ?? true) {
+        $close = baseline_button([
+            'variant'  => 'ghost',
+            'size'     => 'sm', // icon-only: core/button's square at the sm size (src/core-button.css)
+            'class'    => 'is-icon-only has-icon ' . BASELINE_DIALOG_CLOSE,
+            'children' => baseline_icon('close') . '<span class="sr-only">' . esc_html__('Close', 'baseline') . '</span>',
+            'attrs'    => ['command' => 'close', 'commandfor' => $id, 'data-slot' => 'dialog-close'],
+        ]);
+    }
+
+    $inner = $header . (string) ($args['body'] ?? '') . (string) ($args['footer'] ?? '') . $close;
+
+    $trigger = ($args['trigger'] ?? null) === false ? '' : baseline_button([
+        'label'   => (string) ($args['trigger'] ?? __('Open', 'baseline')),
+        'variant' => (string) ($args['trigger_variant'] ?? 'outline'),
+        'size'    => (string) ($args['trigger_size'] ?? 'md'),
+        'attrs'   => ['command' => 'show-modal', 'commandfor' => $id, 'data-slot' => 'dialog-trigger'],
+    ]);
+
+    if ($preview) {
+        return $trigger . '<div data-slot="dialog-content" class="' . BASELINE_DIALOG_PREVIEW . '">' . $inner . '</div>';
+    }
+    $labelled = $title !== '' ? ' aria-labelledby="' . esc_attr($id . '-title') . '"' : '';
+    $described = $desc !== '' ? ' aria-describedby="' . esc_attr($id . '-description') . '"' : '';
+    return $trigger . '<dialog id="' . esc_attr($id) . '" data-slot="dialog-content" closedby="any"' . $labelled . $described
+        . ' class="' . esc_attr(trim(BASELINE_DIALOG_CONTENT . ' ' . (string) ($args['class'] ?? ''))) . '">' . $inner . '</dialog>';
+}

package/templates/wordpress/theme/inc/components/item.php

@@ -0,0 +1,111 @@
+<?php
+/**
+ * Baseline Item for template code and the acf/item block (spec: components/item/spec.md). Emits the same markup and
+ * classes as the React Item (registry/src/ui/item/item.tsx):
+ *
+ *   echo baseline_item(['title' => 'Jordan Diaz', 'description' => 'jordan@example.com', 'image' => $url, 'size' => 'sm']);
+ *   echo baseline_item(['title' => 'Docs', 'description' => 'Read the guide', 'href' => '/docs', 'variant' => 'outline']);
+ *
+ * A link item is one <a> (keeps the link role, no listitem role) and renders no actions: nothing interactive may sit
+ * inside a link. Class strings are static maps (ADR-0008): Tailwind scans this file, so every class appears literally.
+ */
+
+declare(strict_types=1);
+
+const BASELINE_ITEM_ROOT = 'group/item flex w-full flex-wrap items-center rounded-(--bl-item-radius) border-(length:--bl-item-border-width) text-(length:--bl-item-title-font-size) leading-(--bl-item-title-line-height) transition-colors duration-100 outline-none focus-visible:border-ring focus-visible:ring-(length:--bl-control-ring-width) focus-visible:ring-ring [a]:transition-colors [a]:hover:bg-muted';
+
+const BASELINE_ITEM_VARIANTS = [
+    'default' => 'border-transparent',
+    'outline' => 'border-border',
+    'muted'   => 'border-transparent bg-(--bl-item-muted-background)',
+];
+
+const BASELINE_ITEM_SIZES = [
+    'md' => 'gap-(--bl-item-md-gap) px-(--bl-item-md-padding-x) py-(--bl-item-md-padding-y)',
+    'sm' => 'gap-(--bl-item-sm-gap) px-(--bl-item-sm-padding-x) py-(--bl-item-sm-padding-y)',
+    'xs' => 'gap-(--bl-item-xs-gap) px-(--bl-item-xs-padding-x) py-(--bl-item-xs-padding-y)',
+];
+
+const BASELINE_ITEM_MEDIA = 'flex shrink-0 items-center justify-center gap-(--bl-item-actions-gap) group-has-data-[slot=item-description]/item:translate-y-0.5 group-has-data-[slot=item-description]/item:self-start [&_svg]:pointer-events-none';
+const BASELINE_ITEM_MEDIA_ICON = '[&_svg]:size-(--bl-item-media-icon-size)';
+const BASELINE_ITEM_MEDIA_IMAGE = 'size-(--bl-item-media-md-size) overflow-hidden rounded-(--bl-item-media-radius) group-data-[size=sm]/item:size-(--bl-item-media-sm-size) group-data-[size=xs]/item:size-(--bl-item-media-xs-size) [&_img]:size-full [&_img]:object-cover [&_img]:m-0 [&_img]:rounded-none';
+
+const BASELINE_ITEM_CONTENT = 'flex flex-1 flex-col gap-(--bl-item-md-content-gap) group-data-[size=sm]/item:gap-(--bl-item-sm-content-gap) group-data-[size=xs]/item:gap-(--bl-item-xs-content-gap)';
+const BASELINE_ITEM_TITLE = 'line-clamp-1 flex w-fit items-center gap-(--bl-item-actions-gap) underline-offset-4 text-(length:--bl-item-title-font-size) leading-(--bl-item-title-line-height) font-(--bl-item-title-font-weight)';
+const BASELINE_ITEM_DESCRIPTION = 'm-0 line-clamp-2 text-start font-normal text-muted-foreground text-(length:--bl-item-description-md-font-size) leading-(--bl-item-description-md-line-height) group-data-[size=sm]/item:text-(length:--bl-item-description-sm-font-size) group-data-[size=sm]/item:leading-(--bl-item-description-sm-line-height) group-data-[size=xs]/item:text-(length:--bl-item-description-xs-font-size) group-data-[size=xs]/item:leading-(--bl-item-description-xs-line-height) [&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-primary';
+const BASELINE_ITEM_ACTIONS = 'flex items-center gap-(--bl-item-actions-gap)';
+
+/** The group: role=list, its gap following the items' size (src/item.css carries it through ACF's wrappers). */
+const BASELINE_ITEM_GROUP = 'group/item-group not-typeset flex w-full flex-col gap-(--bl-item-group-md-gap) has-data-[size=sm]:gap-(--bl-item-group-sm-gap) has-data-[size=xs]:gap-(--bl-item-group-xs-gap)';
+
+/**
+ * @param array{
+ *   title?: string, description?: string, variant?: string, size?: string, icon?: string, image?: string,
+ *   image_alt?: string, href?: string, actions?: string, class?: string, root_attrs?: string
+ * } $args `description` may hold inline HTML (links); `actions` is ready markup (core/buttons InnerBlocks in the block);
+ *   `root_attrs` replaces the root's class attribute (the block passes get_block_wrapper_attributes()).
+ */
+function baseline_item(array $args): string
+{
+    $size = baseline_item_size((string) ($args['size'] ?? 'md'));
+    $href = (string) ($args['href'] ?? '');
+
+    $media = '';
+    if (!empty($args['image'])) {
+        $media = '<div data-slot="item-media" data-variant="image" class="' . BASELINE_ITEM_MEDIA . ' ' . BASELINE_ITEM_MEDIA_IMAGE . '">'
+            . '<img src="' . esc_url((string) $args['image']) . '" alt="' . esc_attr((string) ($args['image_alt'] ?? '')) . '" loading="lazy" decoding="async"></div>';
+    } elseif (!empty($args['icon'])) {
+        $media = '<div data-slot="item-media" data-variant="icon" class="' . BASELINE_ITEM_MEDIA . ' ' . BASELINE_ITEM_MEDIA_ICON . '">'
+            . baseline_icon((string) $args['icon'], 'shrink-0') . '</div>';
+    }
+
+    $content = '<div data-slot="item-content" class="' . BASELINE_ITEM_CONTENT . '">';
+    if (!empty($args['title'])) {
+        $content .= '<div data-slot="item-title" class="' . BASELINE_ITEM_TITLE . '">' . esc_html((string) $args['title']) . '</div>';
+    }
+    if (!empty($args['description'])) {
+        // a link item may not contain links: a nested <a> makes the browser split the row
+        $allowed = ['strong' => [], 'em' => [], 'br' => []];
+        if ($href === '') {
+            $allowed['a'] = ['href' => true, 'target' => true, 'rel' => true];
+        }
+        $content .= '<p data-slot="item-description" class="' . BASELINE_ITEM_DESCRIPTION . '">' . wp_kses((string) $args['description'], $allowed) . '</p>';
+    }
+    $content .= '</div>';
+
+    // nothing interactive inside a link item
+    $actions = ($href === '' && !empty($args['actions']))
+        ? '<div data-slot="item-actions" class="' . BASELINE_ITEM_ACTIONS . '">' . $args['actions'] . '</div>'
+        : '';
+
+    $root = isset($args['root_attrs'])
+        ? (string) $args['root_attrs']
+        : 'class="' . esc_attr(baseline_item_classes((string) ($args['variant'] ?? 'default'), $size, (string) ($args['class'] ?? ''))) . '"';
+    $inner = $media . $content . $actions;
+    return $href !== ''
+        ? '<a href="' . esc_url($href) . '" data-slot="item" data-size="' . $size . '" ' . $root . '>' . $inner . '</a>'
+        : '<div role="listitem" data-slot="item" data-size="' . $size . '" ' . $root . '>' . $inner . '</div>';
+}
+
+/** A size from the three, md otherwise. */
+function baseline_item_size(string $size): string
+{
+    return isset(BASELINE_ITEM_SIZES[$size]) ? $size : 'md';
+}
+
+/** The item root's classes (shared by baseline_item() and the acf/item block's wrapper attributes). */
+function baseline_item_classes(string $variant, string $size, string $extra = ''): string
+{
+    $variant = isset(BASELINE_ITEM_VARIANTS[$variant]) ? $variant : 'default';
+    // not-typeset: an item in post content must not take typeset's paragraph and link rules (ADR-0028)
+    return trim(BASELINE_ITEM_ROOT . ' not-typeset ' . BASELINE_ITEM_VARIANTS[$variant] . ' ' . BASELINE_ITEM_SIZES[baseline_item_size($size)] . ' ' . $extra);
+}
+
+/** The acf/item block's Icon select lists the active icon set's vocabulary, as acf/badge's does. */
+add_filter('acf/load_field/key=field_baseline_item_icon', static function (array $field): array {
+    $field['choices'] = ['' => __('None', 'baseline')];
+    foreach (baseline_icons() as $name => $icon) {
+        $field['choices'][$name] = (string) ($icon['label'] ?? $name);
+    }
+    return $field;
+});

package/templates/wordpress/theme/inc/components/popover.php

@@ -0,0 +1,125 @@
+<?php
+/**
+ * Baseline Popover for template code (spec: components/popover/spec.md). Emits the same markup and classes as the React
+ * Popover (registry/src/ui/popover/popover.tsx): a <div popover="auto"> toggled by a Button carrying
+ * command="toggle-popover" commandfor, placed by CSS anchor positioning, so it works with no JavaScript (ladder 1):
+ *
+ *   echo baseline_popover([
+ *       'id' => 'pricing-seats', 'trigger' => 'What counts as a seat?', 'trigger_variant' => 'link',
+ *       'title' => 'Seats', 'description' => 'Everyone who signs in during the month.', 'align' => 'start',
+ *   ]);
+ *
+ * A helper only, no editor block (user, 2026-10-05): popovers on marketing sites belong in templates and patterns, such
+ * as a pricing table's explainers. Class strings are static (ADR-0008) and kept identical to React's.
+ */
+
+declare(strict_types=1);
+
+const BASELINE_POPOVER_CONTENT = 'group/popover-content inset-auto m-0 flex not-open:hidden w-(--bl-popover-width) max-w-[calc(100vw-1rem)] flex-col gap-(--bl-popover-gap) overflow-visible rounded-(--bl-popover-radius) border-0 bg-popover p-(--bl-popover-padding) text-sm text-popover-foreground shadow-md outline-none ring-(length:--bl-popover-border-width) ring-(--bl-popover-border) scale-95 opacity-0 open:translate-0 open:scale-100 open:opacity-100 starting:open:scale-95 starting:open:opacity-0 transition-[opacity,scale,translate,display,overlay] transition-discrete duration-100 motion-reduce:transition-none';
+
+// React's contentVariants side classes: the transform origin and the slide in from the trigger's side.
+const BASELINE_POPOVER_SIDE = [
+    'bottom'       => 'origin-top -translate-y-2 starting:open:-translate-y-2',
+    'top'          => 'origin-bottom translate-y-2 starting:open:translate-y-2',
+    'right'        => 'origin-left -translate-x-2 starting:open:-translate-x-2',
+    'left'         => 'origin-right translate-x-2 starting:open:translate-x-2',
+    'inline-end'   => 'origin-left -translate-x-2 starting:open:-translate-x-2 rtl:origin-right rtl:translate-x-2 rtl:starting:open:translate-x-2',
+    'inline-start' => 'origin-right translate-x-2 starting:open:translate-x-2 rtl:origin-left rtl:-translate-x-2 rtl:starting:open:-translate-x-2',
+];
+
+// position-area per side and alignment, the margin facing the trigger, the flip, the edge alignOffset pushes from
+const BASELINE_POPOVER_AREA = [
+    'bottom'       => ['start' => 'block-end span-inline-end', 'center' => 'block-end', 'end' => 'block-end span-inline-start'],
+    'top'          => ['start' => 'block-start span-inline-end', 'center' => 'block-start', 'end' => 'block-start span-inline-start'],
+    'inline-end'   => ['start' => 'inline-end span-block-end', 'center' => 'inline-end', 'end' => 'inline-end span-block-start'],
+    'inline-start' => ['start' => 'inline-start span-block-end', 'center' => 'inline-start', 'end' => 'inline-start span-block-start'],
+    'right'        => ['start' => 'right span-bottom', 'center' => 'right', 'end' => 'right span-top'],
+    'left'         => ['start' => 'left span-bottom', 'center' => 'left', 'end' => 'left span-top'],
+];
+const BASELINE_POPOVER_SIDE_MARGIN = [
+    'bottom' => 'margin-block-start', 'top' => 'margin-block-end', 'inline-end' => 'margin-inline-start',
+    'inline-start' => 'margin-inline-end', 'right' => 'margin-left', 'left' => 'margin-right',
+];
+const BASELINE_POPOVER_ALIGN_MARGIN = [
+    'bottom' => ['margin-inline-start', 'margin-inline-end'], 'top' => ['margin-inline-start', 'margin-inline-end'],
+    'inline-end' => ['margin-block-start', 'margin-block-end'], 'inline-start' => ['margin-block-start', 'margin-block-end'],
+    'right' => ['margin-top', 'margin-bottom'], 'left' => ['margin-top', 'margin-bottom'],
+];
+
+const BASELINE_POPOVER_HEADER = 'flex flex-col gap-(--bl-popover-header-gap) text-sm';
+const BASELINE_POPOVER_TITLE = 'm-0 text-(length:--bl-popover-title-font-size) leading-(--bl-popover-title-line-height) font-(--bl-popover-title-font-weight)';
+const BASELINE_POPOVER_DESCRIPTION = 'm-0 text-(length:--bl-popover-description-font-size) leading-(--bl-popover-description-line-height) text-muted-foreground';
+
+/** An id as a dashed ident for anchor-name / position-anchor (React's anchorName()). */
+function baseline_popover_anchor(string $id): string
+{
+    return '--' . preg_replace('/[^\w-]/', '_', $id);
+}
+
+/**
+ * @param array{
+ *   id?: string, trigger?: string|false, trigger_variant?: string, trigger_size?: string, title?: string,
+ *   description?: string, body?: string, side?: string, align?: string, side_offset?: int, align_offset?: int,
+ *   label?: string, class?: string
+ * } $args `body` is ready markup. `trigger` false leaves the trigger out: then give your own trigger
+ *   baseline_popover_trigger_attrs($id). Without a title, pass `label` for the panel's accessible name.
+ */
+function baseline_popover(array $args): string
+{
+    $id     = sanitize_html_class((string) ($args['id'] ?? '')) ?: wp_unique_id('popover-');
+    $side   = array_key_exists((string) ($args['side'] ?? ''), BASELINE_POPOVER_AREA) ? (string) $args['side'] : 'bottom';
+    $align  = in_array($args['align'] ?? '', ['start', 'center', 'end'], true) ? (string) $args['align'] : 'center';
+    $title  = (string) ($args['title'] ?? '');
+    $desc   = (string) ($args['description'] ?? '');
+    $offset = (int) ($args['side_offset'] ?? 4);
+    $along  = (int) ($args['align_offset'] ?? 0);
+
+    $header = '';
+    if ($title !== '' || $desc !== '') {
+        $header = '<div data-slot="popover-header" class="' . BASELINE_POPOVER_HEADER . '">'
+            . ($title !== '' ? '<h2 id="' . esc_attr($id . '-title') . '" data-slot="popover-title" class="' . BASELINE_POPOVER_TITLE . '">' . esc_html($title) . '</h2>' : '')
+            . ($desc !== '' ? '<p id="' . esc_attr($id . '-description') . '" data-slot="popover-description" class="' . BASELINE_POPOVER_DESCRIPTION . '">' . esc_html($desc) . '</p>' : '')
+            . '</div>';
+    }
+
+    $style = 'position-anchor:' . baseline_popover_anchor($id) . ';position-area:' . BASELINE_POPOVER_AREA[$side][$align]
+        . ';position-try-fallbacks:' . (in_array($side, ['top', 'bottom'], true) ? 'flip-block' : 'flip-inline')
+        . ';' . BASELINE_POPOVER_SIDE_MARGIN[$side] . ':' . $offset . 'px';
+    if ($align !== 'center' && $along !== 0) {
+        $style .= ';' . BASELINE_POPOVER_ALIGN_MARGIN[$side][$align === 'start' ? 0 : 1] . ':' . $along . 'px';
+    }
+
+    $name = $title !== ''
+        ? ' aria-labelledby="' . esc_attr($id . '-title') . '"'
+        : (isset($args['label']) ? ' aria-label="' . esc_attr((string) $args['label']) . '"' : '');
+    $described = $desc !== '' ? ' aria-describedby="' . esc_attr($id . '-description') . '"' : '';
+
+    $trigger = ($args['trigger'] ?? null) === false ? '' : baseline_button([
+        'label'   => (string) ($args['trigger'] ?? __('Open', 'baseline')),
+        'variant' => (string) ($args['trigger_variant'] ?? 'outline'),
+        'size'    => (string) ($args['trigger_size'] ?? 'md'),
+        'attrs'   => baseline_popover_trigger_attrs($id),
+    ]);
+
+    return $trigger . '<div id="' . esc_attr($id) . '" popover="auto" role="dialog" data-slot="popover-content"'
+        . ' data-side="' . esc_attr($side) . '" data-align="' . esc_attr($align) . '"' . $name . $described
+        // not-typeset: in post content typeset's heading and paragraph rules would restyle the title and description (ADR-0028)
+        . ' class="' . esc_attr(trim(BASELINE_POPOVER_CONTENT . ' not-typeset ' . BASELINE_POPOVER_SIDE[$side] . ' ' . (string) ($args['class'] ?? ''))) . '"'
+        . ' style="' . esc_attr($style) . '">' . $header . (string) ($args['body'] ?? '') . '</div>';
+}
+
+/**
+ * The attributes that make any button the popover's trigger and anchor: for a trigger you render yourself.
+ *
+ * @return array<string, string>
+ */
+function baseline_popover_trigger_attrs(string $id): array
+{
+    return [
+        'type'       => 'button',
+        'command'    => 'toggle-popover',
+        'commandfor' => $id,
+        'style'      => 'anchor-name:' . baseline_popover_anchor($id),
+        'data-slot'  => 'popover-trigger',
+    ];
+}