@mannisto/astro-metadata 1.0.1 → 2.0.0-alpha.1

package/src/lib/favicon.ts

@@ -0,0 +1,167 @@
+import { getConfig } from "./config.ts"
+import type { ResolvedFaviconFile } from "./favicon-files.js"
+import { withBase } from "./url.ts"
+
+/**
+ * The favicon data that the integration gives to the components and the endpoints.
+ */
+export type FaviconInfo = {
+  /** The absolute path of the source file. */
+  source: string
+  /** The background color of the Apple icon. */
+  background: string
+  /** True for an SVG source. Only an SVG source can give an SVG file. */
+  svg: boolean
+  /** A short hash of the source file, for cache busting. */
+  hash: string
+  /** The absolute path of the sharp package. */
+  sharp: string
+  /** The files to generate, with their formats and uses. */
+  files: ResolvedFaviconFile[]
+}
+
+/**
+ * The favicon config: the `favicon` option after the checks.
+ */
+export type FaviconConfig = Omit<FaviconInfo, "sharp">
+
+/**
+ * An icon entry for the `icons` field of a web app manifest.
+ */
+export type ManifestIcon = {
+  src: string
+  sizes: string
+  type: string
+}
+
+/**
+ * A link tag of a generated favicon file.
+ */
+export type FaviconLink = {
+  rel: "icon" | "apple-touch-icon"
+  href: string
+  type?: string
+  sizes?: string
+}
+
+// The order of the link tags: ICO first, then the PNG files, the SVG and the Apple icon
+const LINK_ORDER = { ico: 0, png: 1, svg: 2 }
+
+const MIME_TYPES = {
+  ico: "image/x-icon",
+  png: "image/png",
+  svg: "image/svg+xml",
+}
+
+/**
+ * Returns the size of a file for its link tag: the largest image of an ICO file,
+ * or undefined for an SVG file.
+ */
+function largestSize(file: ResolvedFaviconFile): number | undefined {
+  return file.sizes.length > 0 ? Math.max(...file.sizes) : undefined
+}
+
+/**
+ * The favicons that the `favicon` option of the integration generates.
+ * Without the option, the lists are empty and `config` is undefined.
+ */
+export const Favicon = {
+  /**
+   * Returns the favicon config: the source, the background color and the files.
+   */
+  get config(): FaviconConfig | undefined {
+    const favicon = getConfig().favicon
+    if (!favicon) return undefined
+
+    return {
+      source: favicon.source,
+      background: favicon.background,
+      svg: favicon.svg,
+      hash: favicon.hash,
+      files: favicon.files,
+    }
+  },
+
+  /**
+   * Returns the generated files, with their formats, sizes and uses.
+   */
+  get files(): ResolvedFaviconFile[] {
+    return getConfig().favicon?.files ?? []
+  },
+
+  /**
+   * Returns the URL of a generated file, with the base and a hash of the source.
+   * The hash changes when the source changes, so browsers load the new icon.
+   *
+   * @example Favicon.url("/favicon.ico") // "/favicon.ico?v=3f2a1c9e"
+   */
+  url(path: string): string {
+    const hash = getConfig().favicon?.hash
+    return hash ? `${withBase(path)}?v=${hash}` : withBase(path)
+  },
+
+  /**
+   * Returns the link tags of the generated files, in the recommended order:
+   * the ICO file, the PNG files, the SVG file and the Apple icon.
+   */
+  links(): FaviconLink[] {
+    const order = (file: ResolvedFaviconFile) => {
+      return file.use === "apple" ? 3 : LINK_ORDER[file.type]
+    }
+    const files = Favicon.files
+      .filter((file) => {
+        return file.use !== "manifest"
+      })
+      .sort((a, b) => {
+        return order(a) - order(b) || (a.sizes[0] ?? 0) - (b.sizes[0] ?? 0)
+      })
+
+    return files.map((file) => {
+      const size = largestSize(file)
+      if (file.use === "apple") {
+        return {
+          rel: "apple-touch-icon",
+          href: Favicon.url(file.path),
+          sizes: `${size}x${size}`,
+        }
+      }
+      return {
+        rel: "icon",
+        href: Favicon.url(file.path),
+        type: MIME_TYPES[file.type],
+        sizes: size ? `${size}x${size}` : undefined,
+      }
+    })
+  },
+
+  /**
+   * Returns the icons for the `icons` field of a web app manifest: the PNG files
+   * of 192 px or larger.
+   *
+   * @example
+   * // src/pages/manifest.webmanifest.ts
+   * export const GET = () => Response.json({ name: "My Site", icons: Favicon.icons() })
+   */
+  icons(): ManifestIcon[] {
+    return Favicon.files
+      .filter((file) => {
+        return file.use === "manifest"
+      })
+      .map((file) => {
+        const size = file.sizes[0]
+        return { src: Favicon.url(file.path), sizes: `${size}x${size}`, type: "image/png" }
+      })
+  },
+
+  /**
+   * Generates a favicon file of the config. Returns a 404 response for a path that
+   * is not in the config.
+   *
+   * @param path - The path of the file, e.g. "/favicon-32.png".
+   */
+  async generate(path: string): Promise<Response> {
+    // Loaded only here: the image code needs Node and sharp
+    const { renderFavicon } = await import("./favicon-image.ts")
+    return renderFavicon(path)
+  },
+}

package/src/lib/head.d.ts

@@ -0,0 +1,25 @@
+/** The metadata of a page, read from its HTML. */
+export type HeadData = {
+  /** The `lang` attribute of the html tag. */
+  lang?: string
+  /** The value of `<meta charset>`. */
+  charset?: string
+  /** The texts of all title tags. */
+  titles: string[]
+  /** The first `content` of each meta `name`, `property` or `http-equiv`, in lowercase. */
+  meta: Record<string, string>
+  /** The number of meta tags with each `name`, `property` or `http-equiv`. */
+  metaCount: Record<string, number>
+  /** The attributes of each link tag. */
+  links: Record<string, string>[]
+  /** The texts of the JSON-LD scripts. */
+  schemas: string[]
+}
+
+export declare function parseHead(html: string): HeadData
+
+export declare function findLinks(head: HeadData, rel: string): Record<string, string>[]
+
+export declare function findLink(head: HeadData, rel: string): string | undefined
+
+export declare function isAbsolute(value: string): boolean

package/src/lib/head.js

@@ -0,0 +1,141 @@
+// Plain JavaScript: the integration runs in Node, which does not strip types in node_modules.
+// The dev toolbar app uses the same functions, so the build and the toolbar give the same results.
+
+const ENTITIES = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: " ",
+}
+
+// A tag with its attributes. Quoted values can contain ">".
+const TAG = /<(meta|link)\b((?:[^>"']|"[^"]*"|'[^']*')*)>/gi
+const ATTRIBUTE = /([^\s=/>"']+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g
+const SCRIPT = /<script\b((?:[^>"']|"[^"]*"|'[^']*')*)>([\s\S]*?)<\/script>/gi
+
+/**
+ * Replaces the HTML entities in a text with their characters.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function decode(text) {
+  return text.replace(/&(#x[\da-f]+|#\d+|[a-z]+);/gi, (match, code) => {
+    if (code[0] !== "#") return ENTITIES[code.toLowerCase()] ?? match
+
+    const hex = code[1].toLowerCase() === "x"
+    const point = hex ? parseInt(code.slice(2), 16) : parseInt(code.slice(1), 10)
+    return point <= 0x10ffff ? String.fromCodePoint(point) : match
+  })
+}
+
+/**
+ * Returns the attributes of a tag. The names are in lowercase, the values are decoded.
+ *
+ * @param {string} source - The text between the tag name and ">".
+ * @returns {Record<string, string>}
+ */
+function parseAttributes(source) {
+  /** @type {Record<string, string>} */
+  const attributes = {}
+  for (const match of source.matchAll(ATTRIBUTE)) {
+    const value = match[2] ?? match[3] ?? match[4] ?? ""
+    attributes[match[1].toLowerCase()] = decode(value)
+  }
+  return attributes
+}
+
+/**
+ * Reads the metadata of a page from its HTML.
+ *
+ * @param {string} html - The HTML of the page.
+ * @returns {import("./head").HeadData}
+ */
+export function parseHead(html) {
+  const end = html.search(/<\/head>/i)
+  const head = end === -1 ? html : html.slice(0, end)
+
+  /** @type {Record<string, string>} */
+  const meta = {}
+  /** @type {Record<string, number>} */
+  const metaCount = {}
+  /** @type {Record<string, string>[]} */
+  const links = []
+  let charset
+
+  for (const match of head.matchAll(TAG)) {
+    const attributes = parseAttributes(match[2])
+    if (match[1].toLowerCase() === "link") {
+      links.push(attributes)
+      continue
+    }
+    if (attributes.charset !== undefined) charset = attributes.charset
+
+    const key = (attributes.name ?? attributes.property ?? attributes["http-equiv"])?.toLowerCase()
+    if (!key || attributes.content === undefined) continue
+
+    metaCount[key] = (metaCount[key] ?? 0) + 1
+    // Keep the first value, as crawlers do
+    if (!(key in meta)) meta[key] = attributes.content
+  }
+
+  const titles = [...head.matchAll(/<title\b[^>]*>([\s\S]*?)<\/title>/gi)].map((match) => {
+    return decode(match[1]).trim()
+  })
+
+  // JSON-LD can also be in the body
+  const schemas = [...html.matchAll(SCRIPT)]
+    .filter((match) => {
+      return /application\/ld\+json/i.test(parseAttributes(match[1]).type ?? "")
+    })
+    .map((match) => {
+      return match[2]
+    })
+
+  const lang = /<html\b(?:[^>"']|"[^"]*"|'[^']*')*>/i.exec(html)
+  return {
+    lang: lang ? parseAttributes(lang[0].slice(5, -1)).lang : undefined,
+    charset,
+    titles,
+    meta,
+    metaCount,
+    links,
+    schemas,
+  }
+}
+
+/**
+ * Returns the link tags with a `rel` value, e.g. all "alternate" links.
+ *
+ * @param {import("./head").HeadData} head
+ * @param {string} rel - e.g. "canonical".
+ * @returns {Record<string, string>[]}
+ */
+export function findLinks(head, rel) {
+  return head.links.filter((attributes) => {
+    return (attributes.rel ?? "").toLowerCase().split(/\s+/).includes(rel)
+  })
+}
+
+/**
+ * Returns the `href` of the first link with a `rel` value.
+ *
+ * @param {import("./head").HeadData} head
+ * @param {string} rel - e.g. "canonical".
+ * @returns {string | undefined}
+ */
+export function findLink(head, rel) {
+  return findLinks(head, rel)[0]?.href
+}
+
+/**
+ * Returns true for a URL with "http:" or "https:".
+ *
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isAbsolute(value) {
+  return /^https?:\/\//i.test(value)
+}

package/src/lib/manifest.ts

@@ -0,0 +1,126 @@
+import { getConfig, localize } from "./config.ts"
+import type { Localized } from "./config.ts"
+import { Favicon } from "./favicon.ts"
+import { withBase } from "./url.ts"
+
+/**
+ * The web app manifest to generate. Text values can have one value for each locale:
+ * then each locale gets its own manifest file.
+ */
+export type ManifestConfig = {
+  name: Localized
+  shortName?: Localized
+  description?: Localized
+  /** How the installed app opens. Defaults to "standalone". */
+  display?: "standalone" | "fullscreen" | "minimal-ui" | "browser"
+  /** The page that the installed app opens. Defaults to the site root. */
+  startUrl?: Localized
+  /** Defaults to the `themeColor` of the config, or its light color. */
+  themeColor?: string
+  backgroundColor?: string
+  /** Other manifest fields, e.g. `shortcuts`, copied into the file unchanged. */
+  extra?: Record<string, unknown>
+}
+
+/**
+ * A generated manifest file: its locale, and its folder when it is not at the root.
+ */
+export type ManifestPath = {
+  /** The folder of the file, e.g. "fi" for /fi/manifest.webmanifest. */
+  lang?: string
+  /** The locale of the texts in the file. */
+  locale?: string
+}
+
+/**
+ * Returns the manifest to generate, or undefined for no manifest or your own manifest.
+ */
+function generated(): ManifestConfig | undefined {
+  const manifest = getConfig().manifest
+  return typeof manifest === "object" ? manifest : undefined
+}
+
+/**
+ * The web app manifest of the `manifest` option: an object generates the manifest,
+ * and a string is the path of your own manifest.
+ */
+export const Manifest = {
+  /**
+   * Returns the `manifest` option, or undefined without it.
+   */
+  get config(): ManifestConfig | string | undefined {
+    return getConfig().manifest
+  },
+
+  /**
+   * Returns the generated manifest files. The first locale of the texts uses
+   * /manifest.webmanifest, the other locales use /<locale>/manifest.webmanifest.
+   * Returns an empty list for no manifest or your own manifest.
+   */
+  paths(): ManifestPath[] {
+    const manifest = generated()
+    if (!manifest) return []
+
+    // The locales are the keys of the first localized text
+    const texts = [manifest.name, manifest.shortName, manifest.description, manifest.startUrl]
+    const localized = texts.find((text) => {
+      return typeof text === "object"
+    })
+    if (!localized) return [{}]
+
+    return Object.keys(localized).map((locale, index) => {
+      return { lang: index === 0 ? undefined : locale, locale }
+    })
+  },
+
+  /**
+   * Returns the URL of the manifest for a locale, with the base.
+   * An unknown locale gets the manifest at the root.
+   *
+   * @example Manifest.url("fi") // "/fi/manifest.webmanifest"
+   */
+  url(locale?: string): string | undefined {
+    const manifest = getConfig().manifest
+    if (!manifest) return undefined
+    if (typeof manifest === "string") return withBase(manifest)
+
+    const path = Manifest.paths().find((entry) => {
+      return entry.locale === locale
+    })
+    return withBase(path?.lang ? `/${path.lang}/manifest.webmanifest` : "/manifest.webmanifest")
+  },
+
+  /**
+   * Builds the manifest for a locale, with the generated favicons as its icons.
+   * Returns undefined for no manifest or your own manifest.
+   */
+  build(locale?: string): Record<string, unknown> | undefined {
+    const manifest = generated()
+    if (!manifest) return undefined
+
+    const siteColor = getConfig().themeColor
+    const themeColor =
+      manifest.themeColor ?? (typeof siteColor === "string" ? siteColor : siteColor?.light)
+    const icons = Favicon.icons()
+
+    const json: Record<string, unknown> = {
+      name: localize(manifest.name, locale),
+      short_name: localize(manifest.shortName, locale),
+      description: localize(manifest.description, locale),
+      lang: locale,
+      start_url: withBase(localize(manifest.startUrl, locale) ?? "/"),
+      scope: withBase("/"),
+      display: manifest.display ?? "standalone",
+      theme_color: themeColor,
+      background_color: manifest.backgroundColor,
+      icons: icons.length > 0 ? icons : undefined,
+      ...manifest.extra,
+    }
+
+    // Remove empty fields, so the file has only the values that the config gives
+    for (const key of Object.keys(json)) {
+      if (json[key] === undefined) delete json[key]
+    }
+    return json
+  },
+}

package/src/lib/rules.d.ts

@@ -0,0 +1,73 @@
+import type { HeadData } from "./head"
+
+type RuleBase = {
+  /** A short, unique name, e.g. "og-title-missing". The `rules` option turns a rule off by its id. */
+  id: string
+  /**
+   * The tag of the problem, e.g. "og:title", "title", "hreflang" or "json-ld".
+   * The dev toolbar app opens the row of this tag.
+   */
+  field: string
+  level: "error" | "warning" | "info"
+}
+
+/** A rule that checks the head of one page. */
+export type Rule = RuleBase & {
+  /** True for a search or sharing rule: it does not run on a noindex page. */
+  indexed?: boolean
+  /** Returns the message of a problem, or undefined. Text between backticks shows as code. */
+  check(head: HeadData): string | undefined
+}
+
+/** A built page: its path in the output folder, and its head. */
+export type SitePage = {
+  path: string
+  head: HeadData
+}
+
+/** A problem of one page, found by a site rule. */
+export type SiteProblem = {
+  path: string
+  message: string
+}
+
+/** A rule that compares the pages of the site. Only the build runs it. */
+export type SiteRule = RuleBase & {
+  check(pages: SitePage[]): SiteProblem[]
+}
+
+/** A loaded file of the page. */
+export type Asset = {
+  /** The URL or path of the file. */
+  url: string
+  /** False when the file does not load. */
+  ok: boolean
+  /** The HTTP status of a file that does not load. */
+  status?: number
+  /** The MIME type, e.g. "image/png". */
+  type?: string
+  /** The file size in bytes. */
+  bytes?: number
+  /** The real size of an image, in px. */
+  width?: number
+  height?: number
+}
+
+/** The loaded files of a page. A file that can not be checked, e.g. on another site, is not in the list. */
+export type PageAssets = {
+  image?: Asset
+  icons: Asset[]
+}
+
+/** A rule that checks the files of the page. */
+export type AssetRule = RuleBase & {
+  check(head: HeadData, assets: PageAssets): string | undefined
+}
+
+export declare const LIMITS: { title: number; description: number; shortDescription: number }
+
+export declare const RULES: Rule[]
+
+export declare const SITE_RULES: SiteRule[]
+
+export declare const ASSET_RULES: AssetRule[]