@contentrain/astro-kit 0.4.0 → 0.6.0

package/components/gallery/meta.json

@@ -4,18 +4,18 @@
   "description": "Images in a square grid or in masonry columns, with optional captions. A click shows the image large in a native popover (no script), opens the image file, or does nothing.",
   "category": "section",
   "uses": [],
-  "shared": ["KitImage.astro", "Section.astro", "types.ts"],
+  "shared": ["KitImage.astro", "Section.astro", "image.ts", "types.ts"],
   "variants": {
     "layout": { "options": ["grid", "masonry"], "default": "grid", "description": "grid: square crops in rows. masonry: columns that keep each image's shape." },
     "columns": { "options": ["2", "3", "4"], "default": "3", "description": "Columns on wide screens; phones show two." },
     "open": { "options": ["popover", "link", "none"], "default": "popover", "description": "popover: the image opens large in place (Popover API; Escape or a click outside closes it). link: the thumbnail links to the image file (the WordPress 'link to media file'). none: images only." }
   },
   "props": {
-    "items": { "type": "array", "required": true, "items": { "type": "object", "fields": { "image": { "type": "object", "required": true, "fields": { "src": { "type": "image", "required": true }, "alt": { "type": "string", "required": true }, "width": { "type": "integer" }, "height": { "type": "integer" } } }, "caption": { "type": "string" } } }, "description": "The images in order (core/gallery inner images, Elementor gallery items, Divi gallery_ids)." },
-    "heading": { "type": "string", "description": "Section heading above the images." },
-    "closeLabel": { "type": "string", "description": "Text of the viewer's close button (ui-strings gallery.close)." },
-    "tone": { "type": "select", "options": ["default", "muted", "inverse", "accent"], "description": "Section background." },
-    "id": { "type": "string", "description": "Section id, unique per page: viewer ids derive from it (`<id>-image-<n>`)." }
+    "items": { "type": "array", "label": "Images", "required": true, "items": { "type": "object", "fields": { "image": { "type": "image", "label": "Image", "required": true, "description": "The image." }, "imageAlt": { "type": "string", "label": "Image description", "description": "What the image shows, for readers who cannot see it." }, "caption": { "type": "string", "label": "Caption", "description": "Caption under the enlarged image." } } }, "description": "The images in order (core/gallery inner images, Elementor gallery items, Divi gallery_ids)." },
+    "heading": { "type": "string", "label": "Heading", "description": "Section heading above the images." },
+    "closeLabel": { "type": "string", "content": false, "description": "Text of the viewer's close button (ui-strings gallery.close)." },
+    "tone": { "type": "select", "options": ["default", "muted", "inverse", "accent"], "content": false, "description": "Section background." },
+    "id": { "type": "string", "content": false, "description": "Section id, unique per page: viewer ids derive from it (`<id>-image-<n>`)." }
   },
   "slots": {},
   "js": "none",

package/components/header/Header.astro

@@ -53,12 +53,14 @@ interface Props {
 
 const { siteName, tagline, brandSize, linkNav, logo, showName = true, homeHref = '/', items, action, navLabel, menuLabel, closeLabel, layout, tone, position } = Astro.props
 const { root, inner, brand } = header({ layout, tone, position })
+// A tagline under the name keeps its line on a phone, as themes print it: the navigation wraps below.
+const wrap = tagline ? 'flex-wrap md:flex-nowrap' : undefined
 ---
 <header class={root()}>
-  <div class={inner()}>
+  <div class={inner({ class: wrap })}>
     {tagline
       ? (
-        <div class="flex flex-col gap-1">
+        <div class="flex min-w-0 basis-full flex-col gap-1 md:basis-auto">
           <a href={homeHref} class={brand()} aria-label={showName ? undefined : siteName} style={brandSize ? `font-size: ${brandSize}` : undefined} data-kit-brand>
             {logo && <KitImage image={logo} priority class="h-8 w-auto" sizes="160px" />}
             {showName && <span>{siteName}</span>}
@@ -72,8 +74,8 @@ const { root, inner, brand } = header({ layout, tone, position })
           {showName && <span>{siteName}</span>}
         </a>
       )}
-    <div class:list={['flex items-center gap-4', layout === 'centered' ? 'justify-center' : 'ml-auto', linkNav && 'text-[color:var(--color-link,var(--color-accent))]']}>
-      <Nav items={items} label={navLabel} menuLabel={menuLabel} closeLabel={closeLabel} part="nav-header" align={layout === 'centered' ? 'center' : 'end'} />
+    <div class:list={['flex items-center gap-4', layout === 'centered' ? 'justify-center' : 'ml-auto']}>
+      <Nav items={items} label={navLabel} menuLabel={menuLabel} closeLabel={closeLabel} part="nav-header" color={linkNav ? 'link' : 'current'} align={layout === 'centered' ? 'center' : 'end'} />
       {action && <Button action={action} size="sm" class="hidden md:inline-flex" />}
     </div>
   </div>

package/components/header/fixtures.json

@@ -121,5 +121,6 @@
         }
       ]
     }
-  }
+  },
+  { "name": "tagline", "props": { "siteName": "Golden Agency", "tagline": "Websites that sell what you make", "items": [{ "label": "Home", "href": "/" }, { "label": "Services", "href": "/services/" }, { "label": "Contact", "href": "/contact/" }], "menuLabel": "Menu", "closeLabel": "Close" } }
 ]

package/components/hero/meta.json

@@ -42,6 +42,7 @@
   "props": {
     "heading": {
       "type": "string",
+      "label": "Heading",
       "required": true,
       "description": "The main heading (Cover/Group heading, Elementor heading, Divi header title)."
     },
@@ -52,39 +53,51 @@
         "2"
       ],
       "default": "1",
+      "content": false,
       "description": "Heading level: 1 when the hero opens the page, 2 when the page already has an h1."
     },
     "eyebrow": {
       "type": "string",
+      "label": "Eyebrow",
       "description": "Short line above the heading."
     },
     "lead": {
       "type": "text",
+      "label": "Lead",
       "description": "Paragraph under the heading."
     },
     "actions": {
       "type": "array",
+      "label": "Buttons",
       "items": {
         "type": "object",
         "fields": {
           "label": {
             "type": "string",
-            "required": true
+            "label": "Label",
+            "required": true,
+            "description": "The button text."
           },
           "href": {
             "type": "url",
-            "required": true
+            "label": "Link",
+            "required": true,
+            "description": "Where the button goes: a page on this site or a full address."
           },
           "newTab": {
-            "type": "boolean"
+            "type": "boolean",
+            "label": "Open in a new tab",
+            "description": "Open the link in a new tab (an external site the reader should not leave for)."
           },
           "style": {
             "type": "select",
+            "label": "Style",
             "options": [
               "primary",
               "secondary",
               "ghost"
-            ]
+            ],
+            "description": "primary for the main action, secondary or ghost for the ones beside it."
           }
         }
       },
@@ -92,26 +105,35 @@
     },
     "image": {
       "type": "object",
+      "label": "Image",
       "fields": {
         "src": {
           "type": "image",
-          "required": true
+          "label": "Image",
+          "required": true,
+          "description": "The image file."
         },
         "alt": {
           "type": "string",
-          "required": true
+          "label": "Image description",
+          "description": "What the image shows, for readers who cannot see it; empty when it is decoration."
         },
         "width": {
-          "type": "integer"
+          "type": "integer",
+          "label": "Width",
+          "description": "Width in pixels, as uploaded."
         },
         "height": {
-          "type": "integer"
+          "type": "integer",
+          "label": "Height",
+          "description": "Height in pixels, as uploaded."
         }
       },
       "description": "Hero image; loaded first (the page's largest image)."
     },
     "id": {
       "type": "string",
+      "content": false,
       "description": "Anchor id of the section; the heading gets `<id>-title`."
     }
   },

package/components/logo-cloud/LogoCloud.astro

@@ -0,0 +1,69 @@
+---
+// A grid of client or partner logos, each optionally linked, under an
+// optional heading.
+import { tv } from 'tailwind-variants'
+import KitImage from '../_shared/KitImage.astro'
+import Section, { type Tone } from '../_shared/Section.astro'
+import { imageOf, type ImageSource } from '../_shared/image'
+
+const cloud = tv({
+  slots: {
+    heading: 'mb-8 text-center text-sm font-semibold tracking-wide uppercase opacity-80',
+    list: 'grid grid-cols-2 items-center gap-x-8 gap-y-10 sm:grid-cols-3',
+    item: 'flex items-center justify-center',
+    logo: 'h-10 w-auto max-w-full object-contain transition duration-200',
+  },
+  variants: {
+    columns: {
+      '2': { list: 'sm:grid-cols-2' },
+      '3': { list: 'md:grid-cols-3' },
+      '4': { list: 'md:grid-cols-4' },
+    },
+    style: {
+      plain: {},
+      // Colour comes back on hover and on keyboard focus of the logo's link.
+      grayscale: { logo: 'opacity-70 grayscale group-hover:opacity-100 group-hover:grayscale-0 group-focus-visible:opacity-100 group-focus-visible:grayscale-0' },
+    },
+    tone: { default: {}, muted: {}, inverse: {}, accent: { heading: 'opacity-100' } },
+  },
+  defaultVariants: { columns: '4', style: 'plain', tone: 'default' },
+})
+
+interface Item {
+  /** The logo's address (or, until 0.7, an `ImageInput`). */
+  image: ImageSource
+  /** The company's name, read in place of the logo. */
+  imageAlt: string
+  href?: string | undefined
+}
+
+interface Props {
+  heading?: string | undefined
+  items: Item[]
+  columns?: '2' | '3' | '4' | undefined
+  style?: 'plain' | 'grayscale' | undefined
+  tone?: Tone | undefined
+  id?: string | undefined
+}
+
+const { heading, items, columns, style, tone, id } = Astro.props
+const s = cloud({ columns, style, tone })
+const headingId = heading && id ? `${id}-title` : undefined
+---
+<Section tone={tone} id={id} aria-labelledby={headingId}>
+  {heading && <h2 id={headingId} class={s.heading()}>{heading}</h2>}
+  <ul class={s.list()}>
+    {items.map(item => {
+      const image = imageOf(item.image, item.imageAlt)
+      if (!image) return null
+      const logo = <KitImage image={image} sizes="160px" class={s.logo()} />
+      return (
+        <li class={s.item()}>
+          {item.href
+            ? <a href={item.href} class="group rounded-sm focus-visible:outline-2 focus-visible:outline-offset-4">{logo}</a>
+            : <span class="group">{logo}</span>}
+        </li>
+      )
+    })}
+  </ul>
+</Section>

package/components/logo-cloud/fixtures.json

@@ -0,0 +1,139 @@
+[
+  {
+    "name": "four-plain",
+    "props": {
+      "heading": "Trusted by",
+      "items": [
+        {
+          "image": "/kit-fixtures/logo.svg",
+          "imageAlt": "Company 1",
+          "href": "https://example.com"
+        },
+        {
+          "image": "/kit-fixtures/logo.svg",
+          "imageAlt": "Company 2"
+        },
+        {
+          "image": "/kit-fixtures/logo.svg",
+          "imageAlt": "Company 3",
+          "href": "https://example.com"
+        },
+        {
+          "image": "/kit-fixtures/logo.svg",
+          "imageAlt": "Company 4"
+        },
+        {
+          "image": "/kit-fixtures/logo.svg",
+          "imageAlt": "Company 5",
+          "href": "https://example.com"
+        },
+        {
+          "image": "/kit-fixtures/logo.svg",
+          "imageAlt": "Company 6"
+        },
+        {
+          "image": "/kit-fixtures/logo.svg",
+          "imageAlt": "Company 7",
+          "href": "https://example.com"
+        },
+        {
+          "image": "/kit-fixtures/logo.svg",
+          "imageAlt": "Company 8"
+        }
+      ]
+    }
+  },
+  {
+    "name": "three-grayscale-muted",
+    "props": {
+      "heading": "Our partners",
+      "items": [
+        {
+          "image": "/kit-fixtures/logo.svg",
+          "imageAlt": "Company 1",
+          "href": "https://example.com"
+        },
+        {
+          "image": "/kit-fixtures/logo.svg",
+          "imageAlt": "Company 2"
+        },
+        {
+          "image": "/kit-fixtures/logo.svg",
+          "imageAlt": "Company 3",
+          "href": "https://example.com"
+        },
+        {
+          "image": "/kit-fixtures/logo.svg",
+          "imageAlt": "Company 4"
+        },
+        {
+          "image": "/kit-fixtures/logo.svg",
+          "imageAlt": "Company 5",
+          "href": "https://example.com"
+        },
+        {
+          "image": "/kit-fixtures/logo.svg",
+          "imageAlt": "Company 6"
+        }
+      ],
+      "columns": "3",
+      "style": "grayscale",
+      "tone": "muted"
+    }
+  },
+  {
+    "name": "two-inverse",
+    "props": {
+      "items": [
+        {
+          "image": "/kit-fixtures/logo.svg",
+          "imageAlt": "Company 1",
+          "href": "https://example.com"
+        },
+        {
+          "image": "/kit-fixtures/logo.svg",
+          "imageAlt": "Company 2"
+        },
+        {
+          "image": "/kit-fixtures/logo.svg",
+          "imageAlt": "Company 3",
+          "href": "https://example.com"
+        },
+        {
+          "image": "/kit-fixtures/logo.svg",
+          "imageAlt": "Company 4"
+        }
+      ],
+      "columns": "2",
+      "tone": "inverse"
+    }
+  },
+  {
+    "name": "accent",
+    "props": {
+      "heading": "Featured in",
+      "items": [
+        {
+          "image": "/kit-fixtures/logo.svg",
+          "imageAlt": "Company 1",
+          "href": "https://example.com"
+        },
+        {
+          "image": "/kit-fixtures/logo.svg",
+          "imageAlt": "Company 2"
+        },
+        {
+          "image": "/kit-fixtures/logo.svg",
+          "imageAlt": "Company 3",
+          "href": "https://example.com"
+        },
+        {
+          "image": "/kit-fixtures/logo.svg",
+          "imageAlt": "Company 4"
+        }
+      ],
+      "tone": "accent",
+      "style": "grayscale"
+    }
+  }
+]

package/components/logo-cloud/meta.json

@@ -0,0 +1,107 @@
+{
+  "id": "logo-cloud",
+  "name": "Logo cloud",
+  "description": "A grid of client or partner logos, each optionally linked, under an optional heading (\"Trusted by\").",
+  "category": "section",
+  "uses": [],
+  "shared": [
+    "KitImage.astro",
+    "Section.astro",
+    "image.ts",
+    "types.ts"
+  ],
+  "variants": {
+    "columns": {
+      "options": [
+        "2",
+        "3",
+        "4"
+      ],
+      "default": "4",
+      "description": "Logos per row on wide screens; two on phones, three on tablets."
+    },
+    "style": {
+      "options": [
+        "plain",
+        "grayscale"
+      ],
+      "default": "plain",
+      "description": "plain: logos in their own colours. grayscale: muted grey, full colour on hover or focus."
+    },
+    "tone": {
+      "options": [
+        "default",
+        "muted",
+        "inverse",
+        "accent"
+      ],
+      "default": "default",
+      "description": "Section background."
+    }
+  },
+  "props": {
+    "heading": {
+      "type": "string",
+      "label": "Heading",
+      "description": "Line above the logos (Trusted by, Our partners)."
+    },
+    "items": {
+      "type": "array",
+      "label": "Logos",
+      "required": true,
+      "items": {
+        "type": "object",
+        "fields": {
+          "image": {
+            "type": "image",
+            "label": "Logo",
+            "required": true,
+            "description": "The logo file."
+          },
+          "imageAlt": {
+            "type": "string",
+            "label": "Name",
+            "required": true,
+            "description": "The company's name, read in place of the logo."
+          },
+          "href": {
+            "type": "url",
+            "label": "Link",
+            "description": "The company's site, when the logo links there."
+          }
+        }
+      },
+      "description": "The logos, in order (a Gutenberg gallery or columns of logos, Elementor image carousel/gallery of logos, Divi images)."
+    },
+    "id": {
+      "type": "string",
+      "content": false,
+      "description": "Anchor id of the section; the heading gets `<id>-title`."
+    }
+  },
+  "slots": {},
+  "js": "none",
+  "dependencies": {},
+  "sources": {
+    "gutenberg": [
+      "core/gallery"
+    ],
+    "elementor": [
+      "elementor/image-gallery",
+      "elementor/image-carousel"
+    ],
+    "divi": [
+      "divi/et_pb_gallery"
+    ]
+  },
+  "a11y": "A list of logos; each logo's text is the company's name, and a linked logo is one link named by it. The section is labelled by its heading.",
+  "pattern": {
+    "summary": "row of small logos, often linked",
+    "signals": [
+      "4+ images",
+      "small images",
+      "little or no text",
+      "optional heading"
+    ]
+  }
+}

package/components/nav/Nav.astro

@@ -8,7 +8,7 @@ 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',
+    link: 'no-underline aria-[current=page]:font-semibold',
     // 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',
@@ -17,8 +17,14 @@ const nav = tv({
     // 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' } },
+    // current: the surrounding text, dimmed until hovered. link: the site's link colour at full strength, as themes that
+    // colour every link draw their menu; the toggle keeps the surrounding text.
+    color: {
+      current: { link: 'text-current opacity-80 hover:opacity-100 aria-[current=page]:opacity-100' },
+      link: { link: 'text-[color:var(--color-link,var(--color-accent))]' },
+    },
   },
-  defaultVariants: { align: 'end', density: 'compact' },
+  defaultVariants: { align: 'end', density: 'compact', color: 'current' },
 })
 
 interface Props {
@@ -32,14 +38,15 @@ interface Props {
   mobile?: 'popover' | 'details' | undefined
   align?: 'start' | 'end' | 'center' | undefined
   density?: 'compact' | 'comfortable' | undefined
+  color?: 'current' | 'link' | undefined
   /** Unique per page when a page has two navigations. */
   id?: string | undefined
   /** What the navigation is, for checks that find a page's parts (`data-cr-part`, e.g. "nav-header"). */
   part?: string | undefined
 }
 
-const { items, label = 'Main', menuLabel = 'Menu', closeLabel = 'Close', mobile = 'popover', align, density, id = 'site-nav', part } = Astro.props
-const { list, link, sub, toggle } = nav({ align, density })
+const { items, label = 'Main', menuLabel = 'Menu', closeLabel = 'Close', mobile = 'popover', align, density, color, id = 'site-nav', part } = Astro.props
+const { list, link, sub, toggle } = nav({ align, density, color })
 const current = Astro.url.pathname
 const drawer = `${id}-drawer`
 ---

package/components/nav/fixtures.json

@@ -61,6 +61,7 @@
     "props": {
       "id": "fx-nav-c",
       "align": "center",
+      "color": "link",
       "items": [
         {
           "label": "Work",

package/components/nav/meta.json

@@ -32,6 +32,14 @@
       ],
       "default": "compact",
       "description": "Gap and text size of the inline list."
+    },
+    "color": {
+      "options": [
+        "current",
+        "link"
+      ],
+      "default": "current",
+      "description": "current: the surrounding text, dimmed until hovered. link: the site's link colour (--color-link, else the accent) at full strength."
     }
   },
   "props": {

package/components/newsletter/meta.json

@@ -30,11 +30,13 @@
   "props": {
     "action": {
       "type": "url",
+      "label": "Form address",
       "required": true,
       "description": "The provider's hosted form endpoint (Mailchimp *.list-manage.com/subscribe/post, Kit app.kit.com/forms/<n>/subscriptions, MailerLite assets.mailerlite.com/jsonp/<n>/forms/<n>/subscribe, Brevo *.sibforms.com/serve/, Buttondown buttondown.com/api/emails/embed-subscribe/). At migration the engine reads it from the source form element (`dom:form@action`) into the section's content, where it stays editable in Studio; it never passes through the fact pack or a model."
     },
     "provider": {
       "type": "select",
+      "label": "Email provider",
       "options": [
         "mailchimp",
         "kit",
@@ -48,44 +50,54 @@
     },
     "emailName": {
       "type": "string",
+      "label": "Email field name",
       "description": "Field name for the address when the provider is other or names it differently."
     },
     "askName": {
       "type": "boolean",
+      "label": "Ask for a name",
       "default": false,
       "description": "Ask for a first name too, when the provider takes one (the source form had a name field)."
     },
     "heading": {
       "type": "string",
+      "label": "Heading",
       "description": "Section heading."
     },
     "intro": {
       "type": "text",
+      "label": "Introduction",
       "description": "A line or two about the newsletter."
     },
     "note": {
       "type": "string",
+      "label": "Note",
       "description": "Small print under the form (privacy, frequency)."
     },
     "emailLabel": {
       "type": "string",
+      "content": false,
       "description": "ui-strings newsletter.email."
     },
     "nameLabel": {
       "type": "string",
+      "content": false,
       "description": "ui-strings newsletter.name."
     },
     "submitLabel": {
       "type": "string",
+      "content": false,
       "description": "ui-strings newsletter.submit."
     },
     "newTab": {
       "type": "boolean",
       "default": true,
+      "content": false,
       "description": "Open the provider's confirmation page in a new tab (the reader keeps the site)."
     },
     "id": {
       "type": "string",
+      "content": false,
       "description": "Section id, unique per page (two sign-ups on one page need two ids): the heading gets `<id>-title`, the inputs `<id>-email`/`<id>-name`."
     }
   },