@contentrain/astro-kit 0.1.0

package/components/header/Header.astro

@@ -0,0 +1,62 @@
+---
+// Site header: brand (logo and/or name), navigation and an optional call to
+// action.
+import { tv } from 'tailwind-variants'
+import Button from '../_shared/Button.astro'
+import KitImage from '../_shared/KitImage.astro'
+import type { ActionInput, ImageInput, NavItem } from '../_shared/types'
+import Nav from '../nav/Nav.astro'
+
+const header = tv({
+  slots: {
+    root: 'z-40 w-full',
+    inner: 'container-page flex items-center gap-6 py-4',
+    brand: 'flex shrink-0 items-center gap-3 text-lg font-semibold tracking-tight text-current no-underline',
+  },
+  variants: {
+    layout: {
+      split: { inner: 'justify-between' },
+      centered: { inner: 'flex-col gap-3 md:gap-4' },
+      'brand-left': { inner: 'justify-start [&>nav]:ml-10' },
+    },
+    tone: {
+      default: { root: 'border-b border-line bg-surface text-ink' },
+      inverse: { root: 'bg-ink text-surface' },
+      transparent: { root: 'absolute inset-x-0 top-0 bg-transparent text-surface' },
+    },
+    position: { static: {}, sticky: { root: 'sticky top-0' } },
+  },
+  defaultVariants: { layout: 'split', tone: 'default', position: 'static' },
+})
+
+interface Props {
+  siteName: string
+  logo?: ImageInput | undefined
+  /** Show the site name next to the logo. */
+  showName?: boolean | undefined
+  homeHref?: string | undefined
+  items: NavItem[]
+  action?: ActionInput | undefined
+  navLabel?: string | undefined
+  menuLabel?: string | undefined
+  closeLabel?: string | undefined
+  layout?: 'split' | 'centered' | 'brand-left' | undefined
+  tone?: 'default' | 'inverse' | 'transparent' | undefined
+  position?: 'static' | 'sticky' | undefined
+}
+
+const { siteName, logo, showName = true, homeHref = '/', items, action, navLabel, menuLabel, closeLabel, layout, tone, position } = Astro.props
+const { root, inner, brand } = header({ layout, tone, position })
+---
+<header class={root()}>
+  <div class={inner()}>
+    <a href={homeHref} class={brand()} aria-label={showName ? undefined : siteName}>
+      {logo && <KitImage image={logo} priority class="h-8 w-auto" sizes="160px" />}
+      {showName && <span>{siteName}</span>}
+    </a>
+    <div class:list={['flex items-center gap-4', layout === 'centered' ? 'justify-center' : 'ml-auto']}>
+      <Nav items={items} label={navLabel} menuLabel={menuLabel} closeLabel={closeLabel} align={layout === 'centered' ? 'center' : 'end'} />
+      {action && <Button action={action} size="sm" class="hidden md:inline-flex" />}
+    </div>
+  </div>
+</header>

package/components/header/fixtures.json

@@ -0,0 +1,125 @@
+[
+  {
+    "name": "split",
+    "props": {
+      "siteName": "Northwind Journal",
+      "items": [
+        {
+          "label": "Journal",
+          "href": "/"
+        },
+        {
+          "label": "About",
+          "href": "/about/"
+        },
+        {
+          "label": "Contact",
+          "href": "/contact/"
+        }
+      ],
+      "action": {
+        "label": "Subscribe",
+        "href": "/subscribe/"
+      }
+    }
+  },
+  {
+    "name": "centered-inverse",
+    "props": {
+      "siteName": "Northwind Journal",
+      "layout": "centered",
+      "tone": "inverse",
+      "items": [
+        {
+          "label": "Journal",
+          "href": "/"
+        },
+        {
+          "label": "Guides",
+          "href": "/category/guides/"
+        },
+        {
+          "label": "About",
+          "href": "/about/"
+        }
+      ]
+    }
+  },
+  {
+    "name": "brand-left-logo",
+    "props": {
+      "siteName": "Northwind",
+      "layout": "brand-left",
+      "logo": {
+        "src": "/kit-fixtures/logo.svg",
+        "alt": "",
+        "width": 32,
+        "height": 32
+      },
+      "items": [
+        {
+          "label": "Work",
+          "href": "/work/"
+        },
+        {
+          "label": "Studio",
+          "href": "/studio/"
+        }
+      ]
+    }
+  },
+  {
+    "name": "transparent-sticky",
+    "frame": "dark",
+    "props": {
+      "siteName": "Northwind Journal",
+      "tone": "transparent",
+      "position": "sticky",
+      "items": [
+        {
+          "label": "Journal",
+          "href": "/"
+        },
+        {
+          "label": "About",
+          "href": "/about/"
+        }
+      ],
+      "action": {
+        "label": "Get in touch",
+        "href": "/contact/",
+        "style": "ghost"
+      }
+    }
+  },
+  {
+    "name": "split-submenu-last",
+    "props": {
+      "siteName": "Northwind",
+      "items": [
+        {
+          "label": "Journal",
+          "href": "/"
+        },
+        {
+          "label": "About",
+          "href": "/about/"
+        },
+        {
+          "label": "Services",
+          "href": "/services/",
+          "children": [
+            {
+              "label": "Design systems",
+              "href": "/services/design/"
+            },
+            {
+              "label": "Migrations",
+              "href": "/services/migrations/"
+            }
+          ]
+        }
+      ]
+    }
+  }
+]

package/components/header/meta.json

@@ -0,0 +1,34 @@
+{
+  "id": "header",
+  "name": "Header",
+  "description": "Site header: brand (logo and/or name), navigation and an optional call-to-action button.",
+  "category": "chrome",
+  "uses": ["nav"],
+  "shared": ["Button.astro", "KitImage.astro", "types.ts"],
+  "variants": {
+    "layout": { "options": ["split", "centered", "brand-left"], "default": "split", "description": "split: brand left, navigation right. centered: brand above centred navigation. brand-left: navigation right after the brand." },
+    "tone": { "options": ["default", "inverse", "transparent"], "default": "default", "description": "Surface with a bottom border, dark (ink) background, or transparent over the hero that follows." },
+    "position": { "options": ["static", "sticky"], "default": "static", "description": "Sticky keeps the header at the top while scrolling." }
+  },
+  "props": {
+    "siteName": { "type": "string", "required": true, "description": "Site title (site.title)." },
+    "logo": { "type": "object", "fields": { "src": { "type": "image", "required": true }, "alt": { "type": "string", "required": true }, "width": { "type": "integer" }, "height": { "type": "integer" } }, "description": "Logo image (site.logo)." },
+    "showName": { "type": "boolean", "default": true, "description": "Show the site name next to the logo." },
+    "homeHref": { "type": "url", "default": "/", "description": "Where the brand links." },
+    "items": { "type": "array", "required": true, "items": { "type": "object", "fields": { "label": { "type": "string", "required": true }, "href": { "type": "url", "required": true }, "newTab": { "type": "boolean" }, "children": { "type": "array" } } }, "description": "Primary menu (menus → menu-items)." },
+    "action": { "type": "object", "fields": { "label": { "type": "string", "required": true }, "href": { "type": "url", "required": true }, "style": { "type": "select", "options": ["primary", "secondary", "ghost"] } }, "description": "Header button, shown on wide screens." },
+    "navLabel": { "type": "string", "description": "Accessible name of the navigation (ui-strings nav.label)." },
+    "menuLabel": { "type": "string", "description": "Narrow-screen toggle text (ui-strings nav.menu)." },
+    "closeLabel": { "type": "string", "description": "Drawer close text (ui-strings nav.close)." }
+  },
+  "slots": {},
+  "js": "none",
+  "dependencies": {},
+  "sources": {
+    "gutenberg": ["core/template-part:header", "core/site-title", "core/site-logo"],
+    "elementor": ["elementor/theme-site-logo", "elementor/theme-site-title"],
+    "divi": ["divi/et_pb_menu"],
+    "classic": ["classic/header"]
+  },
+  "a11y": "One <header> landmark; the brand link is named by the site name when only the logo shows. Navigation as in nav."
+}

package/components/hero/Hero.astro

@@ -0,0 +1,84 @@
+---
+// The page's opening section: heading, lead, actions and an image — beside the
+// text, below it, or behind it as a cover with the text over a scrim.
+import { tv } from 'tailwind-variants'
+import Button from '../_shared/Button.astro'
+import KitImage from '../_shared/KitImage.astro'
+import Section from '../_shared/Section.astro'
+import type { ActionInput, ImageInput } from '../_shared/types'
+
+const hero = tv({
+  slots: {
+    grid: 'grid items-center gap-10',
+    copy: 'flex flex-col gap-5',
+    eyebrow: 'text-sm font-semibold tracking-wide uppercase opacity-80',
+    heading: 'text-4xl font-bold tracking-tight text-balance md:text-5xl lg:text-6xl',
+    lead: 'max-w-2xl text-lg text-pretty opacity-85 md:text-xl',
+    actions: 'flex flex-wrap gap-3 pt-2',
+    media: 'overflow-hidden rounded-card',
+  },
+  variants: {
+    layout: {
+      split: { grid: 'md:grid-cols-2' },
+      centered: { copy: 'items-center text-center', lead: 'mx-auto', actions: 'justify-center', media: 'mx-auto w-full max-w-4xl' },
+      cover: { grid: 'relative z-10 min-h-[28rem] md:min-h-[36rem]', copy: 'max-w-3xl' },
+    },
+    // accent/accent-ink is only ~5:1 — dimming text on it drops body copy under 4.5:1 (WCAG 1.4.3), so accent keeps it at full strength.
+    tone: { default: {}, muted: {}, inverse: {}, accent: { eyebrow: 'opacity-100', lead: 'opacity-100' } },
+  },
+  defaultVariants: { layout: 'split', tone: 'default' },
+})
+
+interface Props {
+  heading: string
+  /** Heading level: 1 when the hero opens the page (the default), 2 inside a page that already has one. */
+  level?: 1 | 2 | undefined
+  eyebrow?: string | undefined
+  lead?: string | undefined
+  actions?: ActionInput[] | undefined
+  image?: ImageInput | undefined
+  layout?: 'split' | 'centered' | 'cover' | undefined
+  tone?: 'default' | 'muted' | 'inverse' | 'accent' | undefined
+  id?: string | undefined
+}
+
+const { heading, level = 1, eyebrow, lead, actions = [], image, layout = 'split', tone, id } = Astro.props
+const s = hero({ layout, tone })
+const Heading = level === 1 ? 'h1' : 'h2'
+const headingId = id ? `${id}-title` : undefined
+const cover = layout === 'cover' && image
+---
+{cover
+  ? (
+    <Section tone="inverse" spacing="none" width="none" id={id} aria-labelledby={headingId} class="relative isolate overflow-hidden">
+      <KitImage image={image} priority sizes="100vw" class="absolute inset-0 -z-10 h-full w-full object-cover" />
+      <div class="absolute inset-0 -z-10 bg-ink/60" aria-hidden="true" />
+      <div class="container-page py-16 md:py-28">
+        <div class={s.grid()}>
+          <div class={s.copy()}>
+            {eyebrow && <p class={s.eyebrow()}>{eyebrow}</p>}
+            <Heading id={headingId} class={s.heading()}>{heading}</Heading>
+            {lead && <p class={s.lead()}>{lead}</p>}
+            {actions.length > 0 && <div class={s.actions()}>{actions.map(action => <Button action={action} size="lg" />)}</div>}
+          </div>
+        </div>
+      </div>
+    </Section>
+  )
+  : (
+    <Section tone={tone} spacing="lg" id={id} aria-labelledby={headingId}>
+      <div class={s.grid()}>
+        <div class={s.copy()}>
+          {eyebrow && <p class={s.eyebrow()}>{eyebrow}</p>}
+          <Heading id={headingId} class={s.heading()}>{heading}</Heading>
+          {lead && <p class={s.lead()}>{lead}</p>}
+          {actions.length > 0 && <div class={s.actions()}>{actions.map(action => <Button action={action} size="lg" />)}</div>}
+        </div>
+        {image && (
+          <div class={s.media()}>
+            <KitImage image={image} priority sizes={layout === 'split' ? '(min-width: 768px) 50vw, 100vw' : '(min-width: 1024px) 56rem, 100vw'} class="h-auto w-full object-cover" />
+          </div>
+        )}
+      </div>
+    </Section>
+  )}

package/components/hero/fixtures.json

@@ -0,0 +1,95 @@
+[
+  {
+    "name": "split",
+    "props": {
+      "eyebrow": "Northwind Journal",
+      "heading": "Field notes on slow travel and good coffee",
+      "lead": "Essays, guides and photographs from twelve years on the road — now in one place, and easier to read.",
+      "actions": [
+        {
+          "label": "Start reading",
+          "href": "/journal/"
+        },
+        {
+          "label": "About the journal",
+          "href": "/about/",
+          "style": "ghost"
+        }
+      ],
+      "image": {
+        "src": "/kit-fixtures/photo-1.svg",
+        "alt": "A café terrace in the morning",
+        "width": 1200,
+        "height": 800
+      }
+    }
+  },
+  {
+    "name": "centered-muted",
+    "props": {
+      "heading": "Plan a calmer trip",
+      "lead": "Our guides pick fewer places and give each one more time.",
+      "layout": "centered",
+      "tone": "muted",
+      "level": 2,
+      "actions": [
+        {
+          "label": "Browse guides",
+          "href": "/category/guides/"
+        }
+      ],
+      "image": {
+        "src": "/kit-fixtures/photo-2.svg",
+        "alt": "",
+        "width": 1600,
+        "height": 700
+      }
+    }
+  },
+  {
+    "name": "cover",
+    "props": {
+      "heading": "The long way round",
+      "lead": "A year of trains across Europe, one station at a time.",
+      "layout": "cover",
+      "actions": [
+        {
+          "label": "Read the series",
+          "href": "/series/long-way/"
+        }
+      ],
+      "image": {
+        "src": "/kit-fixtures/photo-3.svg",
+        "alt": "",
+        "width": 1600,
+        "height": 900
+      }
+    }
+  },
+  {
+    "name": "inverse-text-only",
+    "props": {
+      "heading": "Contact",
+      "lead": "Questions, corrections and invitations are all welcome.",
+      "tone": "inverse",
+      "level": 2
+    }
+  },
+  {
+    "name": "accent",
+    "props": {
+      "heading": "Spring issue is out",
+      "tone": "accent",
+      "level": 2,
+      "actions": [
+        {
+          "label": "Read it",
+          "href": "/issues/spring/",
+          "style": "secondary"
+        }
+      ],
+      "lead": "Twelve new guides, and the long read on night trains.",
+      "eyebrow": "New"
+    }
+  }
+]

package/components/hero/meta.json

@@ -0,0 +1,127 @@
+{
+  "id": "hero",
+  "name": "Hero",
+  "description": "The page's opening section: optional eyebrow, heading, lead, action buttons and an image — beside the text, below it, or behind it as a full-bleed cover with a scrim.",
+  "category": "section",
+  "uses": [],
+  "shared": [
+    "Button.astro",
+    "KitImage.astro",
+    "Section.astro",
+    "types.ts"
+  ],
+  "variants": {
+    "layout": {
+      "options": [
+        "split",
+        "centered",
+        "cover"
+      ],
+      "default": "split",
+      "description": "split: text and image side by side (stacked on phones). centered: centred text with the image below. cover: the image fills the section behind the text, darkened by a scrim; without an image it falls back to split."
+    },
+    "tone": {
+      "options": [
+        "default",
+        "muted",
+        "inverse",
+        "accent"
+      ],
+      "default": "default",
+      "description": "Section background (ignored by cover, which is always light text on the image)."
+    }
+  },
+  "props": {
+    "heading": {
+      "type": "string",
+      "required": true,
+      "description": "The main heading (Cover/Group heading, Elementor heading, Divi header title)."
+    },
+    "level": {
+      "type": "select",
+      "options": [
+        "1",
+        "2"
+      ],
+      "default": "1",
+      "description": "Heading level: 1 when the hero opens the page, 2 when the page already has an h1."
+    },
+    "eyebrow": {
+      "type": "string",
+      "description": "Short line above the heading."
+    },
+    "lead": {
+      "type": "text",
+      "description": "Paragraph under the heading."
+    },
+    "actions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "fields": {
+          "label": {
+            "type": "string",
+            "required": true
+          },
+          "href": {
+            "type": "url",
+            "required": true
+          },
+          "newTab": {
+            "type": "boolean"
+          },
+          "style": {
+            "type": "select",
+            "options": [
+              "primary",
+              "secondary",
+              "ghost"
+            ]
+          }
+        }
+      },
+      "description": "Buttons, in order."
+    },
+    "image": {
+      "type": "object",
+      "fields": {
+        "src": {
+          "type": "image",
+          "required": true
+        },
+        "alt": {
+          "type": "string",
+          "required": true
+        },
+        "width": {
+          "type": "integer"
+        },
+        "height": {
+          "type": "integer"
+        }
+      },
+      "description": "Hero image; loaded first (the page's largest image)."
+    },
+    "id": {
+      "type": "string",
+      "description": "Anchor id of the section; the heading gets `<id>-title`."
+    }
+  },
+  "slots": {},
+  "js": "none",
+  "dependencies": {},
+  "sources": {
+    "gutenberg": [
+      "core/cover",
+      "core/media-text"
+    ],
+    "divi": [
+      "divi/et_pb_fullwidth_header",
+      "divi/et_pb_fullwidth_image"
+    ],
+    "classic": [
+      "classic/hero"
+    ]
+  },
+  "a11y": "A labelled region (aria-labelledby the heading). One h1 by default; `level: 2` inside pages that already have one. The cover image is decorative when its alt is empty; text sits on an ink scrim for contrast."
+}

package/components/nav/Nav.astro

@@ -0,0 +1,102 @@
+---
+// Site navigation. Wide screens get an inline list whose submenus open on
+// hover and keyboard focus; narrow screens get a toggle that opens the menu as
+// a native popover (drawer) or a <details> dropdown. No JavaScript.
+import { tv } from 'tailwind-variants'
+import type { NavItem } from '../_shared/types'
+
+const nav = tv({
+  slots: {
+    list: 'hidden items-center md:flex',
+    link: 'text-current no-underline opacity-80 hover:opacity-100 aria-[current=page]:font-semibold aria-[current=page]:opacity-100',
+    // hidden, not invisible: a closed submenu takes no space, so one under the last item cannot widen the page.
+    sub: 'absolute top-full z-30 hidden min-w-48 rounded-lg border border-line bg-surface p-2 text-ink shadow-lg group-hover:block group-focus-within:block',
+    toggle: 'inline-flex cursor-pointer list-none items-center gap-2 rounded-md px-3 py-2 text-sm font-medium hover:bg-current/10 md:hidden [&::-webkit-details-marker]:hidden',
+  },
+  variants: {
+    // Submenus open towards the page: leftwards under an end-aligned menu.
+    align: { start: { list: 'justify-start', sub: 'left-0' }, end: { list: 'justify-end', sub: 'right-0' }, center: { list: 'justify-center', sub: 'left-0' } },
+    density: { compact: { list: 'gap-5 text-sm' }, comfortable: { list: 'gap-8 text-base' } },
+  },
+  defaultVariants: { align: 'end', density: 'compact' },
+})
+
+interface Props {
+  items: NavItem[]
+  /** Accessible name of the navigation landmark ("Main"). */
+  label?: string | undefined
+  /** Text on the narrow-screen toggle ("Menu"). */
+  menuLabel?: string | undefined
+  /** Text on the drawer's close button ("Close"). */
+  closeLabel?: string | undefined
+  mobile?: 'popover' | 'details' | undefined
+  align?: 'start' | 'end' | 'center' | undefined
+  density?: 'compact' | 'comfortable' | undefined
+  /** Unique per page when a page has two navigations. */
+  id?: string | undefined
+}
+
+const { items, label = 'Main', menuLabel = 'Menu', closeLabel = 'Close', mobile = 'popover', align, density, id = 'site-nav' } = Astro.props
+const { list, link, sub, toggle } = nav({ align, density })
+const current = Astro.url.pathname
+const drawer = `${id}-drawer`
+---
+{items.length > 0 && (
+  <nav aria-label={label} class="relative">
+    <ul class={list()}>
+      {items.map(item => (
+        <li class="group relative">
+          <a href={item.href} aria-current={item.href === current ? 'page' : undefined} target={item.newTab ? '_blank' : undefined} rel={item.newTab ? 'noopener' : undefined} class={link()}>{item.label}</a>
+          {item.children && item.children.length > 0 && (
+            <ul class={sub()}>
+              {item.children.map(child => (
+                <li><a href={child.href} aria-current={child.href === current ? 'page' : undefined} class="block rounded-md px-3 py-2 text-sm text-ink no-underline hover:bg-surface-muted">{child.label}</a></li>
+              ))}
+            </ul>
+          )}
+        </li>
+      ))}
+    </ul>
+
+    {mobile === 'popover'
+      ? (
+        <>
+          <button type="button" popovertarget={drawer} class={toggle()}>
+            <svg aria-hidden="true" viewBox="0 0 24 24" class="size-5" fill="none" stroke="currentColor" stroke-width="2"><path d="M4 6h16M4 12h16M4 18h16" /></svg>
+            {menuLabel}
+          </button>
+          <div id={drawer} popover class="m-0 ml-auto h-dvh max-h-none w-80 max-w-[85vw] border-l border-line bg-surface p-6 text-ink shadow-xl backdrop:bg-ink/40">
+            <button type="button" popovertarget={drawer} popovertargetaction="hide" class="mb-6 ml-auto flex items-center gap-2 rounded-md px-3 py-2 text-sm font-medium hover:bg-surface-muted">
+              <svg aria-hidden="true" viewBox="0 0 24 24" class="size-5" fill="none" stroke="currentColor" stroke-width="2"><path d="M6 6l12 12M18 6L6 18" /></svg>
+              {closeLabel}
+            </button>
+            <ul class="flex flex-col gap-1">
+              {items.map(item => (
+                <li>
+                  <a href={item.href} aria-current={item.href === current ? 'page' : undefined} class="block rounded-md px-3 py-2 text-ink no-underline hover:bg-surface-muted aria-[current=page]:font-semibold">{item.label}</a>
+                  {item.children && item.children.length > 0 && (
+                    <ul class="ml-3 border-l border-line pl-3">
+                      {item.children.map(child => <li><a href={child.href} class="block rounded-md px-3 py-1.5 text-sm text-ink-muted no-underline hover:text-ink">{child.label}</a></li>)}
+                    </ul>
+                  )}
+                </li>
+              ))}
+            </ul>
+          </div>
+        </>
+      )
+      : (
+        <details class="relative md:hidden">
+          <summary class={toggle()}>
+            <svg aria-hidden="true" viewBox="0 0 24 24" class="size-5" fill="none" stroke="currentColor" stroke-width="2"><path d="M4 6h16M4 12h16M4 18h16" /></svg>
+            {menuLabel}
+          </summary>
+          <ul class="absolute right-0 z-30 mt-2 flex w-64 flex-col gap-1 rounded-lg border border-line bg-surface p-3 text-ink shadow-lg">
+            {items.flatMap(item => [item, ...(item.children ?? [])]).map(item => (
+              <li><a href={item.href} aria-current={item.href === current ? 'page' : undefined} class="block rounded-md px-3 py-2 text-sm text-ink no-underline hover:bg-surface-muted">{item.label}</a></li>
+            ))}
+          </ul>
+        </details>
+      )}
+  </nav>
+)}