@mannisto/astro-metadata 2.0.0-alpha.4 → 2.0.0

package/src/lib/page.ts

@@ -0,0 +1,164 @@
+import { getConfig, localize } from "./config.ts"
+import type { MetadataImage } from "./config.ts"
+import { i18n } from "./i18n.ts"
+import type { I18nPage } from "./i18n.ts"
+import { openGraphAlternates, openGraphLocale } from "./open-graph.ts"
+import type { SchemaAuthor, SchemaBreadcrumb, SchemaData } from "./schema.ts"
+import { pageUrl } from "./url.ts"
+
+export type HreflangLink = {
+  /** The locale of the version, e.g. "en", "fi" or "en-US", or "x-default". */
+  hreflang: string
+  /** The path or URL of the page in that locale. */
+  href: string
+}
+
+/** The props of `<Metadata>`. The small components take the props that they use. */
+export type MetadataProps = {
+  /** The page title. The title template of the config adds the site name. */
+  title?: string
+  /** Defaults to the description of the config. */
+  description?: string
+  /** The social image. Defaults to the image of the config. */
+  image?: MetadataImage
+  /**
+   * The Open Graph type. Defaults to "website". "article" also adds the `Article`
+   * structured data, with the title, the description, the image and the dates.
+   */
+  type?: string
+  /**
+   * The author of an article: a name, or `{ name, url, twitter }`. The Twitter (X) handle
+   * gives `twitter:creator`.
+   */
+  author?: SchemaAuthor | SchemaAuthor[]
+  /** The publication date of an article. */
+  published?: Date | string
+  /** The date of the last change of an article. */
+  modified?: Date | string
+  /**
+   * The canonical path or URL. Defaults to the current page. With `@mannisto/astro-i18n`,
+   * the default is the public URL of the page.
+   */
+  canonical?: string
+  /** Set to false to keep the page out of search results. Defaults to true. */
+  index?: boolean
+  /** Set to false to tell search engines not to follow the links. Defaults to true. */
+  follow?: boolean
+  /**
+   * The hreflang links: the page in each locale, and `x-default`. With `@mannisto/astro-i18n`
+   * or the `i18n` option of Astro, the links are made for you. `[]` turns them off.
+   */
+  hreflang?: HreflangLink[]
+  /** The path from the home page to this page. It adds the `BreadcrumbList` structured data. */
+  breadcrumbs?: SchemaBreadcrumb[]
+  /**
+   * Structured data items of your own, e.g. a `Product`. They go into the structured data
+   * of the page, with the site from the config.
+   */
+  schema?: SchemaData | SchemaData[]
+  /**
+   * The locale of the page. Defaults to `Astro.currentLocale`, or the locale of
+   * `@mannisto/astro-i18n`.
+   */
+  locale?: string
+}
+
+/**
+ * Returns the full title of a page: the title in the title template, or the site name
+ * for a page without a title.
+ *
+ * @example fullTitle("About") // "About | My Site"
+ */
+export function fullTitle(title?: string, locale?: string): string | undefined {
+  const config = getConfig()
+  if (!title) return localize(config.siteName, locale)
+
+  const template = localize(config.titleTemplate, locale)
+  if (!template?.includes("%s")) return title
+
+  // A replacer function keeps "$&" and other "$" patterns in the title as text
+  return template.replace("%s", () => {
+    return title
+  })
+}
+
+/**
+ * Returns the locale of the page: the prop, `Astro.currentLocale`, or the locale of the
+ * i18n setup of the project.
+ */
+export function pageLocale(page: I18nPage, props: MetadataProps): string | undefined {
+  return props.locale ?? page.currentLocale ?? i18n?.locale(page)
+}
+
+/**
+ * Returns the absolute canonical URL of the page: the prop, the public path of the
+ * i18n setup, or the current path.
+ */
+export function pageCanonical(page: I18nPage, props: MetadataProps): string {
+  return pageUrl(props.canonical ?? i18n?.path(page) ?? page.url.pathname)
+}
+
+/**
+ * Returns the hreflang links of the page: the prop, or the links of the i18n setup.
+ */
+export function pageHreflang(page: I18nPage, props: MetadataProps): HreflangLink[] {
+  return props.hreflang ?? i18n?.alternates(page) ?? []
+}
+
+/**
+ * Returns the social image of the page: the prop, or the image of the config with the alt
+ * text of the locale.
+ */
+export function pageImage(props: MetadataProps, locale?: string): MetadataImage | undefined {
+  if (props.image) return props.image
+
+  const image = getConfig().image
+  if (!image) return undefined
+  return { ...image, alt: localize(image.alt, locale) }
+}
+
+/**
+ * Returns the description of the page: the prop, or the description of the config.
+ */
+export function pageDescription(props: MetadataProps, locale?: string): string | undefined {
+  return props.description ?? localize(getConfig().description, locale)
+}
+
+/**
+ * Returns the content of the robots tag, or an empty text. Search engines index and follow
+ * by default, so the tag is only necessary for other values.
+ */
+export function pageRobots(props: MetadataProps): string {
+  const robots = getConfig().robots
+  const index = props.index ?? robots?.index ?? true
+  const follow = props.follow ?? robots?.follow ?? true
+
+  return [!index && "noindex", !follow && "nofollow", robots?.extra].filter(Boolean).join(", ")
+}
+
+/**
+ * Returns the Open Graph locale of the page and its other locales: "fi_FI".
+ */
+export function pageOpenGraphLocales(
+  locale: string | undefined,
+  hreflang: HreflangLink[]
+): { locale?: string; alternates: string[] } {
+  const codes = hreflang.map((link) => {
+    return link.hreflang
+  })
+  return { locale: openGraphLocale(locale), alternates: openGraphAlternates(locale, codes) }
+}
+
+/**
+ * Returns the authors of an article as a list.
+ */
+export function pageAuthors(props: MetadataProps): SchemaAuthor[] {
+  return props.author === undefined ? [] : [props.author].flat()
+}
+
+/**
+ * Returns a date as an ISO 8601 text. A text stays unchanged.
+ */
+export function isoDate(value: Date | string): string {
+  return typeof value === "string" ? value : value.toISOString()
+}

package/src/lib/rules.js

@@ -813,7 +813,6 @@ export const SITE_RULES = [
     field: "hreflang",
     level: "warning",
     check(pages) {
-      // The pages by their canonical URL
       const byUrl = new Map()
       for (const page of pages) {
         const canonical = findLink(page.head, "canonical")

package/src/lib/schema.ts

@@ -1,4 +1,4 @@
-import type { Graph, Thing, WithContext } from "schema-dts"
+import type { Graph, Thing } from "schema-dts"
 
 import { getConfig, localize } from "./config.ts"
 import type { Localized } from "./config.ts"
@@ -8,8 +8,11 @@ import { url } from "./url.ts"
  * A structured data item of your own, e.g. a `Product` or an `Event`. The schema.org types
  * give the editor completion, and other objects are also accepted. `@context` is not
  * necessary: the items go into one graph with the context.
+ *
+ * `@context` is an optional property, not `WithContext<Thing>`: that type makes the union of
+ * schema-dts too large for TypeScript when a layout spreads its props into `<Metadata>`.
  */
-export type SchemaData = Thing | WithContext<Thing> | Record<string, unknown>
+export type SchemaData = (Thing & { "@context"?: string }) | Record<string, unknown>
 
 /**
  * The organization or the person behind the site. It is the publisher of the site and of

package/src/lib/site.ts

@@ -1,73 +1,95 @@
 import { getConfig, localize } from "./config.ts"
-import type { MetadataConfig } from "./config.ts"
-import { pageUrl, url } from "./url.ts"
+import type { MetadataImage, ThemeColor } from "./config.ts"
+import { Favicon } from "./favicon.ts"
+import type { ManifestIcon } from "./favicon.ts"
+import { url } from "./url.ts"
+
+/** The options of the `Site` values that can have a text for each locale. */
+export type SiteOptions = {
+  /** The locale of the text, e.g. "fi". Defaults to the first text. */
+  locale?: string
+}
 
 /**
- * The site values of the integration, and absolute URLs with the Astro `site` and `base`.
+ * The values that you set in the integration. Each method returns `undefined` for an
+ * option that is not set.
+ *
+ * @example Site.description({ locale: "fi" })
  */
 export const Site = {
   /**
-   * Returns the site values of the integration. Without the integration, all values are undefined.
+   * Returns the `siteName` of the locale.
+   *
+   * @example Site.name() // "Acme Studio"
    */
-  get config(): MetadataConfig {
-    const config = getConfig()
-    return {
-      siteName: config.siteName,
-      titleTemplate: config.titleTemplate,
-      description: config.description,
-      image: config.image,
-      twitter: config.twitter,
-      themeColor: config.themeColor,
-      feeds: config.feeds,
-      robots: config.robots,
-      manifest: config.manifest,
-      schema: config.schema,
-    }
+  name(options: SiteOptions = {}): string | undefined {
+    return localize(getConfig().siteName, options.locale)
+  },
+
+  /**
+   * Returns the `titleTemplate` of the locale.
+   *
+   * @example Site.template() // "%s | Acme Studio"
+   */
+  template(options: SiteOptions = {}): string | undefined {
+    return localize(getConfig().titleTemplate, options.locale)
   },
 
   /**
-   * Returns the name of the site for a locale.
+   * Returns the `description` of the locale.
    *
-   * @param locale - e.g. "fi". A missing locale uses the first value.
+   * @example Site.description({ locale: "fi" })
    */
-  name(locale?: string): string | undefined {
-    return localize(getConfig().siteName, locale)
+  description(options: SiteOptions = {}): string | undefined {
+    return localize(getConfig().description, options.locale)
   },
 
   /**
-   * Returns the full title of a page: the title in the title template, or the site name
-   * for a page without a title.
+   * Returns the `image` with an absolute URL, and the alt text of the locale.
    *
-   * @example Site.title("About") // "About | My Site"
+   * @example Site.image() // { url: "https://example.com/og.jpg", alt: "Acme Studio", … }
    */
-  title(title?: string, locale?: string): string | undefined {
-    const template = localize(getConfig().titleTemplate, locale)
-    if (!title) return Site.name(locale)
-    if (!template?.includes("%s")) return title
+  image(options: SiteOptions = {}): MetadataImage | undefined {
+    const image = getConfig().image
+    if (!image) return undefined
 
-    // A replacer function keeps "$&" and other "$" patterns in the title as text
-    return template.replace("%s", () => {
-      return title
-    })
+    return {
+      url: url(image.url),
+      alt: localize(image.alt, options.locale),
+      width: image.width,
+      height: image.height,
+    }
   },
 
   /**
-   * Returns the absolute URL of a path, with the Astro `site` and `base`.
-   * Absolute URLs stay unchanged.
+   * Returns the `twitter` values. The card defaults to "summary_large_image".
    *
-   * @example Site.url("/og.jpg") // "https://example.com/og.jpg"
+   * @example Site.twitter() // { site: "@acmestudio", card: "summary_large_image" }
+   */
+  twitter(): { site?: string; card: "summary" | "summary_large_image" } | undefined {
+    const twitter = getConfig().twitter
+    if (!twitter) return undefined
+
+    return {
+      site: twitter.site,
+      card: twitter.card ?? "summary_large_image",
+    }
+  },
+
+  /**
+   * Returns the `themeColor`: one color, or `{ light, dark }`.
    */
-  url(path: string): string {
-    return url(path)
+  themeColor(): ThemeColor | undefined {
+    return getConfig().themeColor
   },
 
   /**
-   * Returns the absolute URL of a page, with or without the slash at the end,
-   * the same as the Astro `trailingSlash` and `build.format` settings.
+   * Returns the icons of the generated favicons, for the `icons` field of your own web app
+   * manifest. Without the `favicon` option, the list is empty.
    *
-   * @example Site.pageUrl("/blog") // "https://example.com/blog/"
+   * @example export const GET = () => Response.json({ name: "Acme Studio", icons: Site.icons() })
    */
-  pageUrl(path: string): string {
-    return pageUrl(path)
+  icons(): ManifestIcon[] {
+    return Favicon.icons()
   },
 }

package/src/lib/url.ts

@@ -62,7 +62,10 @@ export function pagePath(path: string): string {
     if (buildFormat === "preserve") return path
     slash = buildFormat !== "file"
   }
-  const clean = path.replace(/\/+$/, "")
+  // A loop and not a regular expression: /\/+$/ is slow for a path with many slashes
+  let end = path.length
+  while (end > 0 && path[end - 1] === "/") end--
+  const clean = path.slice(0, end)
   return slash ? `${clean}/` : clean || "/"
 }
 

package/src/runtime.ts

@@ -1,9 +1,7 @@
 export type { Feed, Localized, MetadataConfig, MetadataImage, ThemeColor } from "./lib/config.ts"
 export type { FaviconFile, ResolvedFaviconFile } from "./lib/favicon-files.js"
 export type { FaviconConfig, FaviconLink, ManifestIcon } from "./lib/favicon.ts"
-export { Favicon } from "./lib/favicon.ts"
 export type { ManifestConfig, ManifestPath } from "./lib/manifest.ts"
-export { Manifest } from "./lib/manifest.ts"
 export type {
   SchemaAuthor,
   SchemaBreadcrumb,
@@ -12,5 +10,5 @@ export type {
   SchemaPage,
   SchemaPublisher,
 } from "./lib/schema.ts"
-export { Schema } from "./lib/schema.ts"
+export type { SiteOptions } from "./lib/site.ts"
 export { Site } from "./lib/site.ts"

package/src/toolbar/app.ts

@@ -15,7 +15,6 @@ export default defineToolbarApp({
     canvas.append(panel)
     let open = false
 
-    // The badge shows the worst problem of the page
     async function updateBadge() {
       const { checks } = await checkPage()
       const { level } = summarize(checks)
@@ -44,18 +43,8 @@ export default defineToolbarApp({
       setOpen(false)
     })
 
-    // Alt+M (Option+M on a Mac) opens and closes the panel. Escape closes it.
-    // `code` is the key, not the character: Option+M types "µ" on a Mac.
     document.addEventListener("keydown", (event) => {
-      const target = event.target as HTMLElement | null
-      if (target?.closest("input, textarea, select, [contenteditable]")) return
-
-      if (event.altKey && event.code === "KeyM") {
-        event.preventDefault()
-        setOpen(!open)
-      } else if (event.key === "Escape" && open) {
-        setOpen(false)
-      }
+      if (event.key === "Escape" && open) setOpen(false)
     })
 
     // View transitions change the page without a full load
@@ -65,8 +54,5 @@ export default defineToolbarApp({
     })
 
     updateBadge()
-
-    // ?metadata in the URL opens the panel when the page loads
-    if (new URLSearchParams(location.search).has("metadata")) setOpen(true)
   },
 })

package/src/toolbar/data.ts

@@ -109,7 +109,6 @@ function jsonLd(): JsonLd[] {
     const source = script.textContent ?? ""
     try {
       const data = JSON.parse(source)
-      // The items of a list, or of a graph
       const list = Array.isArray(data) ? data : [data]
       const items = list.flatMap((item) => {
         return Array.isArray(item?.["@graph"]) ? item["@graph"] : [item]
@@ -239,7 +238,6 @@ export type PageChecks = {
   checks: Check[]
 }
 
-// The check endpoint of the dev server. The integration adds it.
 const CHECK_PATH = "/__astro-metadata/check"
 
 /**

package/src/toolbar/highlight.ts

@@ -1,6 +1,3 @@
-// A small highlighter for the two formats of the panel: JSON and HTML.
-// It wraps each token in a span with a class, and the CSS sets the colors.
-
 export type Language = "json" | "html"
 
 /**

package/src/toolbar/ui/alert/alert.css

@@ -61,7 +61,6 @@
   font-weight: 400;
   height: 100%;
 
-  /* Inline code in the alert uses the colors of the level */
   --code-color: var(--text);
   --code-border: color-mix(in srgb, var(--border) 40%, transparent);
   --code-background: color-mix(in srgb, var(--border) 20%, transparent);
@@ -73,7 +72,6 @@
   }
 }
 
-/* The list of items, each with a dot in the color of its level */
 .items {
   display: grid;
   gap: var(--space-50);

package/src/toolbar/ui/section/section.css

@@ -1,4 +1,3 @@
-/* A box around the section, so its content belongs together */
 :host {
   display: block;
   padding: var(--space-300);
@@ -7,7 +6,6 @@
   background: var(--zinc-900);
 }
 
-/* A closed or empty section shows only its heading */
 :host([closed]),
 :host([empty]) {
   h2 {
@@ -15,17 +13,14 @@
   }
 }
 
-/* An empty section has no caret */
 :host([empty]) astro-metadata-icon {
   visibility: hidden;
 }
 
-/* The caret turns down when the section is open */
 :host(:not([closed])) astro-metadata-icon {
   transform: rotate(90deg);
 }
 
-/* The heading: small, monospace, uppercase, wide letter spacing */
 h2 {
   margin: 0 0 var(--space-200);
   font-family: var(--font-mono);
@@ -36,7 +31,6 @@ h2 {
   letter-spacing: 0.05em;
 }
 
-/* The heading is a button that closes or opens the section */
 button {
   display: flex;
   align-items: center;
@@ -56,7 +50,6 @@ button {
     color: var(--zinc-100);
   }
 
-  /* An empty section: a dim heading and "None" at the right */
   &:disabled {
     color: var(--zinc-600);
     cursor: default;

package/src/toolbar/ui/table/table.css

@@ -1,4 +1,3 @@
-/* A framed container, a hairline between the rows, and a hover color */
 :host {
   display: block;
 }
@@ -31,7 +30,6 @@ tr {
     background: var(--zinc-800);
   }
 
-  /* The child rows are indented under their row */
   &.child th {
     padding-left: calc(var(--space-400) + var(--space-400));
   }

package/src/toolbar/views/metadata-panel.css

@@ -53,13 +53,6 @@
   min-width: 0;
 }
 
-/* The title and the Beta badge */
-.title {
-  display: flex;
-  align-items: center;
-  gap: var(--space-200);
-}
-
 h1 {
   margin: 0;
   font-size: var(--font-size-body);

package/src/toolbar/views/metadata-panel.ts

@@ -6,7 +6,6 @@ import type { PageMetadata } from "../data.ts"
 import { define } from "../define.ts"
 import tokens from "../styles/tokens.css?inline"
 
-import "../ui/badge/badge.ts"
 import "../ui/icon/icon.ts"
 import "../ui/tab-group/tab-group.ts"
 
@@ -105,10 +104,7 @@ export class MetadataPanel extends LitElement {
 
         <header class="header">
           <div class="heading">
-            <div class="title">
-              <h1>Metadata</h1>
-              <astro-metadata-badge level="info">Beta</astro-metadata-badge>
-            </div>
+            <h1>Metadata</h1>
             <p class="path">${location.pathname}</p>
           </div>
           <button class="close" @click=${this.close} aria-label="Close the panel">

package/src/toolbar/views/overview-view.css

@@ -1,10 +1,8 @@
-/* The alerts of the page: one for each level */
 .alerts {
   display: grid;
   gap: var(--space-200);
 }
 
-/* The Open Graph image at the full width of the panel */
 .image {
   width: 100%;
   aspect-ratio: 1.91 / 1;

package/src/toolbar/views/overview-view.ts

@@ -327,6 +327,13 @@ export class OverviewView extends LitElement {
     const data = this.data
     const og = data.openGraph
     const image = findMeta(og, "og:image")
+    const alternates = og
+      .filter((tag) => {
+        return tag.key === "og:locale:alternate"
+      })
+      .map((tag) => {
+        return tag.value
+      })
     const width = findMeta(og, "og:image:width")
     const height = findMeta(og, "og:image:height")
 
@@ -366,6 +373,12 @@ export class OverviewView extends LitElement {
             tagRow("Description", findMeta(og, "og:description"), "og:description"),
             tagRow("Type", code(findMeta(og, "og:type")), "og:type"),
             tagRow("Site name", findMeta(og, "og:site_name"), "og:site_name"),
+            tagRow("Locale", code(findMeta(og, "og:locale")), "og:locale"),
+            tagRow(
+              "Other locales",
+              code(alternates.join(", ") || undefined),
+              "og:locale:alternate"
+            ),
             tagRow("Image", image, "og:image"),
             tagRow(
               "Image size",

package/src/toolbar/views/previews/previews-view.css

@@ -4,7 +4,6 @@
  * look like the platform, not like the panel.
  */
 
-/* The preview at the center of a dotted background */
 .stage {
   display: flex;
   justify-content: center;

package/src/toolbar/views/previews/previews-view.ts

@@ -17,7 +17,6 @@ import { slack } from "./slack.ts"
 import { twitter } from "./twitter.ts"
 import { whatsapp } from "./whatsapp.ts"
 
-// The platforms in the order of the sections
 const PLATFORMS: Platform[] = [google, twitter, facebook, linkedin, whatsapp, discord, slack]
 
 /**