blume 1.5.2 → 1.6.0

package/src/seo/jsonld.ts

@@ -4,6 +4,62 @@ import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 /** A date-ish value carried through frontmatter (string, YAML Date, or unset). */
 type DateInput = string | Date | null;
 
+/** A schema.org `PostalAddress`; every part optional. */
+export interface PostalAddressIdentity {
+  addressCountry?: string;
+  addressLocality?: string;
+  addressRegion?: string;
+  postalCode?: string;
+  streetAddress?: string;
+}
+
+/**
+ * `seo.organization`: the organization behind the site, emitted on every page
+ * as an `Organization` node the WebSite and article nodes cite as publisher.
+ */
+export interface OrganizationIdentity {
+  address?: PostalAddressIdentity;
+  /** `ContactPoint.contactType`; only emitted with an email or telephone. */
+  contactType: string;
+  email?: string;
+  /** Absolute URL or root-relative path (absolutized like page URLs). */
+  logo?: string;
+  /** Defaults to the site title. */
+  name?: string;
+  /** Profile URLs (GitHub, X, LinkedIn, …) that identify the organization. */
+  sameAs: string[];
+  telephone?: string;
+  /** Defaults to the site origin. */
+  url?: string;
+}
+
+/**
+ * `seo.software`: the product the site documents, emitted on the homepage as
+ * a `SoftwareApplication` node — the identity type agents use to tell what a
+ * docs site is about.
+ */
+export interface SoftwareIdentity {
+  applicationCategory: string;
+  /** Defaults to the site description. */
+  description?: string;
+  /** License URL or SPDX identifier. */
+  license?: string;
+  /** Defaults to the site title. */
+  name?: string;
+  operatingSystem?: string;
+  /** Emitted as an `Offer` when set; `0` marks the software free. */
+  price?: number | string;
+  priceCurrency: string;
+  /** Package registry, repository, and profile URLs for the product. */
+  sameAs: string[];
+}
+
+/** The site-level identity nodes, from `seo.organization`/`seo.software`. */
+export interface StructuredDataIdentity {
+  organization?: OrganizationIdentity;
+  software?: SoftwareIdentity;
+}
+
 /** Inputs for a page's JSON-LD, all known at render time in RootLayout. */
 export interface StructuredDataInput {
   siteName: string;
@@ -24,6 +80,12 @@ export interface StructuredDataInput {
   /** BCP-47 language tag for `inLanguage`; defaults to `en`. */
   locale?: string;
   breadcrumbs: Crumb[];
+  /**
+   * Site identity (`seo.organization`, `seo.software`). Both nodes need an
+   * absolute `@id`, so they are emitted only when `siteUrl` is set — like the
+   * WebSite node.
+   */
+  identity?: StructuredDataIdentity | null;
 }
 
 /** schema.org `@type` for each content type; defaults to TechArticle. */
@@ -66,11 +128,193 @@ export const toIso = (value: DateInput | undefined): string | undefined => {
   return Number.isNaN(date.getTime()) ? undefined : date.toISOString();
 };
 
+/** Copy the defined string entries of `source` onto a fresh node. */
+const definedStrings = (
+  source: Record<string, string | undefined>
+): JsonLdNode => {
+  const node: JsonLdNode = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (value) {
+      node[key] = value;
+    }
+  }
+  return node;
+};
+
 /**
- * Build a schema.org JSON-LD `@graph` for a page: site identity, the page as an
- * article, and its breadcrumb trail. Returns null when there is nothing useful
- * to emit (e.g. the homepage without a configured site). URLs are absolute when
- * `siteUrl` is set, otherwise route-relative.
+ * The `Organization` node: name and URL (defaulting to the site's), logo, the
+ * `sameAs` profiles, a `ContactPoint` when there is a way to make contact,
+ * and a `PostalAddress` when any part of one is given — the fields agents
+ * check to verify a business before recommending it.
+ */
+const organizationNode = (
+  organization: OrganizationIdentity,
+  context: {
+    absolutize: (path: string) => string;
+    id: string;
+    rootUrl: string;
+    siteName: string;
+  }
+): JsonLdNode => {
+  const node: JsonLdNode = {
+    "@id": context.id,
+    "@type": "Organization",
+    name: organization.name ?? context.siteName,
+    url: organization.url ?? context.rootUrl,
+  };
+  if (organization.logo) {
+    node.logo = context.absolutize(organization.logo);
+  }
+  if (organization.email) {
+    node.email = organization.email;
+  }
+  if (organization.telephone) {
+    node.telephone = organization.telephone;
+  }
+  if (organization.email || organization.telephone) {
+    node.contactPoint = {
+      "@type": "ContactPoint",
+      contactType: organization.contactType,
+      ...definedStrings({
+        email: organization.email,
+        telephone: organization.telephone,
+      }),
+    };
+  }
+  const address = organization.address
+    ? definedStrings({ ...organization.address })
+    : {};
+  if (Object.keys(address).length > 0) {
+    node.address = { "@type": "PostalAddress", ...address };
+  }
+  if (organization.sameAs.length > 0) {
+    node.sameAs = organization.sameAs;
+  }
+  return node;
+};
+
+/**
+ * The homepage `SoftwareApplication` node: the product's identity (name,
+ * description, category), an `Offer` when a price is declared (`0` for free
+ * software), license, registry/repository profiles, and the organization as
+ * its publisher when one is configured.
+ */
+const softwareNode = (
+  software: SoftwareIdentity,
+  context: {
+    description?: string;
+    id: string;
+    organizationId: string | null;
+    rootUrl: string;
+    siteName: string;
+  }
+): JsonLdNode => {
+  const node: JsonLdNode = {
+    "@id": context.id,
+    "@type": "SoftwareApplication",
+    applicationCategory: software.applicationCategory,
+    name: software.name ?? context.siteName,
+    url: context.rootUrl,
+  };
+  const description = software.description ?? context.description;
+  if (description) {
+    node.description = description;
+  }
+  if (software.operatingSystem) {
+    node.operatingSystem = software.operatingSystem;
+  }
+  if (software.price !== undefined) {
+    node.offers = {
+      "@type": "Offer",
+      price: String(software.price),
+      priceCurrency: software.priceCurrency,
+    };
+  }
+  if (software.license) {
+    node.license = software.license;
+  }
+  if (software.sameAs.length > 0) {
+    node.sameAs = software.sameAs;
+  }
+  if (context.organizationId) {
+    node.publisher = { "@id": context.organizationId };
+  }
+  return node;
+};
+
+/** The page as an article node (`BlogPosting`/`TechArticle`). */
+const articleNode = (
+  input: StructuredDataInput,
+  context: {
+    base: string | null;
+    organizationId: string | null;
+    pageUrl: string;
+  }
+): JsonLdNode => {
+  const pageType = input.pageType ?? "";
+  const node: JsonLdNode = {
+    "@id": `${context.pageUrl}#page`,
+    "@type": isArticleType(pageType) ? ARTICLE_TYPES[pageType] : "TechArticle",
+    headline: input.title,
+    inLanguage: input.locale || "en",
+    name: input.title,
+    url: context.pageUrl,
+  };
+  if (input.description) {
+    node.description = input.description;
+  }
+  const published = toIso(input.published);
+  if (published) {
+    node.datePublished = published;
+  }
+  const modified = toIso(input.modified);
+  if (modified) {
+    node.dateModified = modified;
+  }
+  if (context.base) {
+    node.isPartOf = { "@id": `${context.base}#website` };
+  }
+  if (context.organizationId) {
+    node.publisher = { "@id": context.organizationId };
+  }
+  return node;
+};
+
+/**
+ * The breadcrumb trail, or null when it is too short to be one. Google
+ * requires `item` on every ListItem except the last; sidebar groups without
+ * an index page produce route-less crumbs, so those are dropped (positions
+ * renumbered) rather than emitted as invalid link-less items.
+ */
+const breadcrumbNode = (
+  breadcrumbs: Crumb[],
+  base: string | null,
+  deployBase: string
+): JsonLdNode | null => {
+  const linked = breadcrumbs.filter(
+    (crumb): crumb is Required<Crumb> => typeof crumb.route === "string"
+  );
+  if (linked.length <= 1) {
+    return null;
+  }
+  return {
+    "@type": "BreadcrumbList",
+    itemListElement: linked.map((crumb, index) => ({
+      "@type": "ListItem",
+      item: absolute(base, withBasePath(deployBase, crumb.route)),
+      name: crumb.label,
+      position: index + 1,
+    })),
+  };
+};
+
+/**
+ * Build a schema.org JSON-LD `@graph` for a page: site identity (the WebSite,
+ * plus the configured Organization everywhere and the SoftwareApplication on
+ * the homepage), the page as an article, and its breadcrumb trail. Returns
+ * null when there is nothing useful to emit (e.g. the homepage without a
+ * configured site). URLs are absolute when `siteUrl` is set, otherwise
+ * route-relative.
  */
 export const buildStructuredData = (
   input: StructuredDataInput
@@ -83,61 +327,59 @@ export const buildStructuredData = (
   const rootUrl = absolute(base, deployBase);
   const graph: JsonLdNode[] = [];
 
+  // Identity nodes carry absolute `@id`s, so they exist only with a site —
+  // the same rule as the WebSite node they attach to.
+  const organization = base ? input.identity?.organization : undefined;
+  const software = base ? input.identity?.software : undefined;
+  const organizationId = organization ? `${base}#organization` : null;
+
   if (base) {
-    graph.push({
+    const website: JsonLdNode = {
       "@id": `${base}#website`,
       "@type": "WebSite",
       name: input.siteName,
       url: rootUrl,
-    });
-  }
-
-  // The homepage is fully described by the WebSite node; deeper pages get an
-  // article node plus a breadcrumb trail.
-  if (input.route !== "/") {
-    const pageType = input.pageType ?? "";
-    const node: JsonLdNode = {
-      "@id": `${pageUrl}#page`,
-      "@type": isArticleType(pageType)
-        ? ARTICLE_TYPES[pageType]
-        : "TechArticle",
-      headline: input.title,
-      inLanguage: input.locale || "en",
-      name: input.title,
-      url: pageUrl,
     };
-    if (input.description) {
-      node.description = input.description;
+    if (organizationId) {
+      website.publisher = { "@id": organizationId };
     }
-    const published = toIso(input.published);
-    if (published) {
-      node.datePublished = published;
-    }
-    const modified = toIso(input.modified);
-    if (modified) {
-      node.dateModified = modified;
-    }
-    if (base) {
-      node.isPartOf = { "@id": `${base}#website` };
-    }
-    graph.push(node);
-
-    // Google requires `item` on every ListItem except the last; sidebar groups
-    // without an index page produce route-less crumbs, so those are dropped
-    // (positions renumbered) rather than emitted as invalid link-less items.
-    const linked = input.breadcrumbs.filter(
-      (crumb): crumb is Required<Crumb> => typeof crumb.route === "string"
+    graph.push(website);
+  }
+  if (organization && organizationId) {
+    graph.push(
+      organizationNode(organization, {
+        // A root-relative logo lives under the deployment base like any
+        // other site asset; an absolute URL passes through.
+        absolutize: (path) =>
+          path.startsWith("/")
+            ? absolute(base, withBasePath(deployBase, path))
+            : path,
+        id: organizationId,
+        rootUrl,
+        siteName: input.siteName,
+      })
     );
-    if (linked.length > 1) {
-      graph.push({
-        "@type": "BreadcrumbList",
-        itemListElement: linked.map((crumb, index) => ({
-          "@type": "ListItem",
-          item: absolute(base, withBasePath(deployBase, crumb.route)),
-          name: crumb.label,
-          position: index + 1,
-        })),
-      });
+  }
+
+  // The homepage is described by the WebSite node (and the product, when one
+  // is configured); deeper pages get an article node plus a breadcrumb trail.
+  if (input.route === "/") {
+    if (software && base) {
+      graph.push(
+        softwareNode(software, {
+          description: input.description,
+          id: `${base}#software`,
+          organizationId,
+          rootUrl,
+          siteName: input.siteName,
+        })
+      );
+    }
+  } else {
+    graph.push(articleNode(input, { base, organizationId, pageUrl }));
+    const breadcrumbs = breadcrumbNode(input.breadcrumbs, base, deployBase);
+    if (breadcrumbs) {
+      graph.push(breadcrumbs);
     }
   }
 

package/src/theme/code-block-padding.ts

@@ -0,0 +1,16 @@
+/**
+ * Vertical padding of a highlighted code block, shared by the theme (which
+ * emits it as CSS) and `<Component>` (which estimates a source pane's SSR
+ * height from it) so the two cannot drift.
+ */
+
+/** Top and bottom inset of a plain prose block with no chrome, in rem. */
+export const CODE_PADDING_BLOCK_REM = 1;
+
+/**
+ * Top inset of a flush block — inside tabs or a `not-prose` component, or an
+ * untitled block with no language bar — where the layout's copy button is
+ * absolutely positioned over the first line: `top-2.5` plus a 1.875rem button
+ * lands at 2.5rem, so the first line starts there.
+ */
+export const FLUSH_CODE_PADDING_TOP_REM = 2.5;

package/src/theme/entry.ts

@@ -1,3 +1,8 @@
+import {
+  CODE_PADDING_BLOCK_REM,
+  FLUSH_CODE_PADDING_TOP_REM,
+} from "./code-block-padding.ts";
+
 interface TailwindEntryOptions {
   /**
    * Globs to scan for utility classes. Typically the Blume package source and
@@ -37,7 +42,10 @@ const TOKEN_DEFAULTS = `:root {
   --blume-background-image-size: cover;
   --blume-foreground: oklch(0.145 0 0);
   --blume-muted: oklch(0.965 0 0);
-  --blume-muted-foreground: oklch(0.54 0 0);
+  /* 5.28:1 on the page background. The headroom over 4.5:1 is the point: muted
+     text is 14px body copy routinely set on a tinted surface (callouts, badges,
+     panels), and each tint costs a few tenths. */
+  --blume-muted-foreground: oklch(0.53 0 0);
   --blume-border: oklch(0.88 0.006 260 / 0.72);
   --blume-accent: oklch(0.145 0 0);
   --blume-accent-foreground: oklch(1 0 0);
@@ -252,6 +260,20 @@ ${THEME_MAPPING}
   color: var(--blume-muted-foreground);
   font-size: 0.875rem;
   line-height: 1.7;
+  /* An unbreakable run — an API permission, a broker list, a bare URL used as
+     its own link text, an OpenAPI operation title of the form
+     \`METHOD /very/long/{path}\`, a module-qualified name in a generated
+     reference — paints past the content column, and nothing between the
+     paragraph and the viewport clips it, so it lands in the document's scroll
+     width and drags the page sideways on a phone. Inherited, so headings and
+     inline code are covered too; the only re-declarations below are the
+     opt-in code-wrap mode and Twoslash, which want different values.
+     \`break-word\` and not \`anywhere\`: only \`anywhere\` reduces min-content,
+     which is what sizes \`table-layout: auto\` columns, so it would resize
+     every table on the site. The flip side is that a token in a table cell
+     still never breaks — the column grows to fit it — so wide tables rely on
+     the .blume-table-scroll wrapper, not on this. */
+  overflow-wrap: break-word;
 }
 
 /* No letter-spacing here: prose headings inherit the base h1-h6 rule's
@@ -260,13 +282,6 @@ ${THEME_MAPPING}
   font-weight: 500;
 }
 
-/* A heading can carry one long unbreakable token — an OpenAPI operation's title
-   is \`METHOD /very/long/{path}\` when the spec sets no summary — which would run
-   off the content column. Break it across lines instead of overflowing. */
-.prose :where(h1, h2, h3, h4, h5, h6) {
-  overflow-wrap: break-word;
-}
-
 .prose :where(h1) {
   font-size: 3rem;
   line-height: 1.1;
@@ -311,6 +326,18 @@ ${THEME_MAPPING}
   opacity: 1;
 }
 
+/* A [toc]-marked heading exists only for the table of contents: it stays in
+   the flow as a zero-height, invisible anchor target so its TOC entry (and any
+   deep link) still has somewhere to scroll to, without rendering on the page. */
+.prose :where(.blume-toc-only) {
+  border: 0;
+  height: 0;
+  margin: 0;
+  overflow: hidden;
+  padding: 0;
+  visibility: hidden;
+}
+
 .prose :where(h2:first-child) {
   border-top: 0;
   padding-top: 0;
@@ -354,7 +381,7 @@ ${THEME_MAPPING}
   line-height: 1.55;
   margin: 1.5rem 0;
   overflow-x: auto;
-  padding: 1rem 0;
+  padding: ${CODE_PADDING_BLOCK_REM}rem 0;
   position: relative;
 }
 
@@ -534,7 +561,6 @@ blume-diff {
    never matches (a cell is not its own descendant). */
 .prose :where(td, th) > code,
 .prose :where(td, th) :not(pre) > code {
-  overflow-wrap: break-word;
   white-space: normal;
 }
 
@@ -578,9 +604,37 @@ blume-tabs [data-blume-tab-content] > pre {
   margin: 0;
 }
 
+/* These contexts drop the language bar (\`::before\` is cleared below), so the
+   bar's padding goes with it and the block keeps the plain inset. Unscoped on
+   purpose: <CodeBlock> wraps its pre in its own \`.prose\` below the component
+   chrome, so without this a titled block on a page with no prose column
+   (PageLayout) would keep the 3.75rem bar padding under a cleared bar. */
 blume-tabs pre[data-language],
 .not-prose pre[data-language] {
-  padding-top: 1rem;
+  padding-top: ${CODE_PADDING_BLOCK_REM}rem;
+}
+
+/* Room for the copy button. The docs layout injects it into every \`.prose pre\`
+   — absolutely positioned against the pre's border box, 1.875rem tall, at
+   \`top-2.5\` in the flush contexts above and \`top-2\` elsewhere — and it is
+   unconditional, so wherever no language bar exists to hold it, it painted
+   over the first line of code: any line long enough to reach the button's
+   strip (a curl invocation, an install command, an import path) went under
+   it. Keyed on the attribute the docs layout stamps on <body>, so the strip
+   only appears where the injector runs (PageLayout pages run none), and on
+   \`.astro-code\` so the playground's response pre — created after the
+   injector ran, never given a button — keeps its plain inset. The first
+   selector is the injector's own flush predicate; the second covers the
+   remaining bar-less Shiki case, an untitled <CodeBlock> in plain prose, from
+   first paint. The third covers a raw \`<pre><code>\` written in prose — no
+   \`.astro-code\`, no language bar, but the injector gives it a button all
+   the same — keyed on that injected button, which is exactly what separates
+   it from the playground's pre. API panel blocks match, but their own
+   !important padding wins and they hide the injected button. */
+[data-blume-code-copy] :is(blume-tabs, .not-prose) pre.astro-code,
+[data-blume-code-copy] .prose pre.astro-code:not([data-language]),
+[data-blume-code-copy] .prose pre:not([data-language]):has(> [data-blume-copy]) {
+  padding-top: ${FLUSH_CODE_PADDING_TOP_REM}rem;
 }
 
 blume-tabs pre[data-language]::before,