@sonordev/contracts 2.9.0 → 2.10.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 2.10.0
+
+A minor release: two new functions in `@sonordev/contracts/page-titles`. Every entry is otherwise unchanged.
+
+- **`page-titles`**: the rule for telling a page's name from its address, once, for everything that prints or stores a title.
+  - `isPageAddress(value, path?)` says whether a value is a page's address and not its name, so a path saved where a title belonged never prints as one. It's true for a path or anything starting with a slash, an absolute URL, a host and path with no scheme ("example.com/services"), a route placeholder, and, given the page's `path`, the path itself without its slashes ("services/ac-repair" for "/services/ac-repair"). Ordinary text with a slash in it ("Heating/Cooling") is a name. Ask it about `titleHead`'s result, not the whole title.
+  - `isPageName(title, path?)` says whether a stored title is a real name for the page, judging every piece between its pipes. A title that's printed whole prints its pipes too, so "Floor Plans | /floor-plans/studio", "Floor Plans | :slug", ":slug | Example Apartments" and the unspaced "Floor Plans|/floor-plans/studio" aren't names, while "1 Bedroom | 1BR 1BA" is. Empty pieces from a stray pipe are left out, a title that's only pipes isn't a name, and neither are empty, nullish or non-string values. A writer asks it about `titleHead`'s result, so the code that stores a name and the code that prints it can't disagree.
+
 ## 2.9.0
 
 A minor release: three new entries, `@sonordev/contracts/page-titles`, `@sonordev/contracts/broadcast-layouts` and `@sonordev/contracts/publication-branding`. Every other entry is unchanged.

package/README.md

@@ -34,7 +34,7 @@ pnpm add @sonordev/contracts
 | `@sonordev/contracts/knowledge` | Which Sonor records Signal reads into a project's knowledge, the address each one's knowledge is stored under (`portfolio://<id>`), and the limits of the call that tells Signal a site's pages changed | the Sonor API sends those calls and Signal answers them |
 | `@sonordev/contracts/business-claims` | What an outbound email or text may say about a business (`checkOutboundCopy`), the stored review of what it claimed and when that review is settled, and whether a sent email arrived intact (`readBackVerdict`) | the Sonor API checks again on the bytes it sends, Signal checks what its writers and agents file |
 | `@sonordev/contracts/outreach` | What a segment of outreach is (pitch, sending mailbox, prospect industry), who may turn one on, what a turned-on segment covers, and what a drip's ledger row means for its lead | Signal writes and reads segment grants, the Sonor API checks the same grant before it sends |
-| `@sonordev/contracts/page-titles` | A page's own name: its title without the brand (`titleHead`), a readable label from a slug (`slugLabel`), and whether a value is a route placeholder like `:slug` (`isRoutePlaceholder`) | Signal's site-architecture writer, the agency site kit's portfolio components |
+| `@sonordev/contracts/page-titles` | A page's own name: its title without the brand (`titleHead`), a readable label from a slug (`slugLabel`), whether a value is a route placeholder like `:slug` (`isRoutePlaceholder`), whether a value is a page's address and not its name (`isPageAddress`), and whether a stored title is a name when every piece between its pipes is judged (`isPageName`) | Signal's site-architecture writer, the agency site kit's portfolio components |
 | `@sonordev/contracts/broadcast-layouts` | Which Broadcast card layouts are drawn (centered `headline`, low `anchor`), which retired IDs still read and what each draws as (`normalizeArticleCoverLayout`), the Broadcast styles, and the review compositions with the frozen draw that gives each review its own (`reviewCardVariationFromDigest`) | the Sonor API's card renderers and settings, Signal's agent tools, the dashboard's pickers |
 | `@sonordev/contracts/publication-branding` | What a publication's branding may hold and what a change may set (`createPublicationBrandingValidator`), how a change merges, the editorial charter, and safe font stacks | the Sonor API stores and resolves it, Signal checks an agent's change before filing it, the dashboard edits it |
 
@@ -551,15 +551,20 @@ HVAC". A list of pages, a sitemap or a case study wants the name alone, and
 the usual shortcuts get it wrong. Capitalizing each word of a slug turns
 "ac-replacement" into "Ac Replacement", "faq" into "Faq" and
 "smith-and-smith" into "Smith And Smith". A title with a stray second pipe
-ships as "Loans | | Brand". `titleHead`, `slugLabel` and `isRoutePlaceholder`
-are the one set of rules, so every list reads the same.
+ships as "Loans | | Brand". A title that is really the page's path ships as a
+page name. `titleHead`, `slugLabel`, `isRoutePlaceholder`, `isPageAddress`
+and `isPageName` are the one set of rules, so every list reads the same.
 
 ```ts
-import { isRoutePlaceholder, slugLabel, titleHead } from '@sonordev/contracts/page-titles'
-
-titleHead('FHA Home Loans | | Example Mortgage') // 'FHA Home Loans'
-slugLabel('/services/hvac-repair/')              // 'HVAC Repair'
-isRoutePlaceholder('/floor-plans/:slug')         // true
+import { isPageAddress, isPageName, isRoutePlaceholder, slugLabel, titleHead } from '@sonordev/contracts/page-titles'
+
+titleHead('FHA Home Loans | | Example Mortgage')           // 'FHA Home Loans'
+slugLabel('/services/hvac-repair/')                         // 'HVAC Repair'
+isRoutePlaceholder('/floor-plans/:slug')                    // true
+isPageAddress('services/ac-repair', '/services/ac-repair')  // true
+isPageAddress('AC Repair', '/services/ac-repair')           // false
+isPageName('1 Bedroom | 1BR 1BA', '/floor-plans/one-bed')   // true
+isPageName('Studio | /floor-plans/studio', '/floor-plans/studio') // false
 ```
 
 - **`titleHead(title)`** is the title without its trailing " | Brand". Only
@@ -612,6 +617,50 @@ isRoutePlaceholder('/floor-plans/:slug')         // true
   single token with no spaces, so ordinary text that contains a colon or a
   bracket isn't one ("Update: new hours", "FAQ / [draft] notes"). Nullish and
   empty values are false.
+- **`isPageAddress(value, path?)`** is true when the value is a page's address
+  and not its name. That's what a title becomes when a writer saved the path
+  where the title belonged. It's true for:
+  - a path, or anything that starts with a slash ("/services/ac-repair",
+    "//example.com/services");
+  - an absolute URL ("https://example.com/services");
+  - a host and a path with no scheme and no spaces ("example.com/services",
+    "www.example.co.uk/floor-plans/", "example.com:8080/x"). A browser shows an
+    untitled page's address this way. A bare host ("example.com") isn't an
+    address, and neither is text that has a slash in it ("Heating/Cooling",
+    "24/7 Emergency Service") or a number that looks like a host ("4.5/5",
+    "v2.10/changelog"), because a host ends in a letters-only domain;
+  - a route placeholder, the way `isRoutePlaceholder` reads one;
+  - the page's own path written without its slashes, when you pass `path`:
+    "services/ac-repair" and "services/ac-repair/" for "/services/ac-repair",
+    "faq" for "/faq". Leading and trailing slashes come off both sides, and
+    the comparison is exact: "ac-repair" isn't the address of
+    "/services/ac-repair", and "Pricing" for "/pricing" is a name where
+    "pricing" is the path.
+
+  The value is trimmed first. Empty, whitespace-only, nullish and non-string
+  values are false: they're nothing, not an address, and what an empty title
+  means is the caller's to say. It judges one string, so cut a brand tail
+  first and ask about what's left: `isPageAddress(titleHead(title), path)`.
+- **`isPageName(title, path?)`** is true when a stored title is a real name for
+  the page: something is left once the pipes are set aside, and no piece
+  between them is a page's address, as `isPageAddress` reads one (given the
+  page's `path`). It's the rule for a title that's printed whole. A writer that
+  stores a name and a reader that prints it both ask it, so they can't disagree
+  about a path, a URL or a placeholder behind a pipe.
+  - **Every piece is judged**, the first and the last included. "Floor Plans |
+    /floor-plans/studio", "Floor Plans | :slug", ":slug | Example Apartments"
+    and "Floor Plans | example.com/floor-plans/studio" aren't names, and neither
+    is the unspaced "Floor Plans|/floor-plans/studio", because it prints with
+    its path in it. The split is on the bare `|`, and the empty pieces of a
+    stray pipe ("| Studio |", "Studio | | Example Apartments") are left out.
+  - **A name with a pipe in it stays a name** while every piece is text:
+    "1 Bedroom | 1BR 1BA", "Heating/Cooling | Update: new hours".
+  - **Nothing left isn't a name.** A title that's only pipes, an empty or
+    whitespace-only title, `null`, `undefined` and a non-string are all false.
+  - **Cut the brand tail first.** It judges the title it's given, tail
+    included. A writer asks about what it stores: `isPageName(titleHead(title),
+    path)`. A path that's only in the cut tail isn't stored, so it doesn't
+    count against the page.
 
 Known limits. A slug carries no capitalization or punctuation, so "DeWalt"
 reads "Dewalt", "joes-pizza" reads "Joes Pizza", and an `index.html` reads

package/dist/page-titles.d.ts

@@ -16,6 +16,15 @@
  *    name or a path, because the page has no title at all.
  *  - `isRoutePlaceholder` says whether a value is a framework route
  *    placeholder (":slug", "[slug]", "[...rest]") and not a page's name.
+ *  - `isPageAddress` says whether a value is a page's address (a path, a
+ *    URL, a route pattern, or the page's own path without its slashes) and
+ *    not its name. It's the one "is this title really a path" rule, so the
+ *    writer of a page list and the reader that prints it can't disagree.
+ *  - `isPageName` says whether a stored title is a name: something is left
+ *    once the pipes are set aside, and no piece between them is an address.
+ *    It's the one rule for a title that gets printed whole, so the writer
+ *    that stores a name and the reader that prints it can't disagree about
+ *    a path, a URL or a placeholder behind a pipe.
  *
  * Pure string logic: no I/O, no Node built-ins. The brand split is
  * seo-meta's `stripTitleSuffix`, imported, never copied: only the LAST
@@ -78,3 +87,54 @@ export declare function slugLabel(input: string): string;
  * false.
  */
 export declare function isRoutePlaceholder(value: string | null | undefined): boolean;
+/**
+ * Whether `value` is a page's address and not its name: what a page's title
+ * becomes when nothing better was stored (the old sitemap writers saved the
+ * path there), or a pattern that leaked out of the router. True for:
+ *
+ *  - a path, or anything starting with a slash ("/services/ac-repair",
+ *    "//example.com/services");
+ *  - an absolute URL ("https://example.com/services");
+ *  - a host and a path with no scheme ("example.com/services");
+ *  - a route placeholder, as `isRoutePlaceholder` reads it ("/floor-plans/:slug",
+ *    ":Slug", "[slug]");
+ *  - the page's own path written without its slashes. Given `path`, the
+ *    comparison drops leading and trailing slashes from both sides, so for
+ *    "/services/ac-repair" the values "services/ac-repair" and
+ *    "services/ac-repair/" are the address, and for "/faq" the value "faq" is.
+ *    It compares the whole path and it's case-sensitive: "ac-repair" isn't
+ *    the address of "/services/ac-repair", and "Pricing" for "/pricing" is a
+ *    name where "pricing" is the path.
+ *
+ * The value is trimmed first. Empty, whitespace-only, nullish and non-string
+ * values give false: they aren't an address, they're nothing, and the caller
+ * decides what an empty title means. `path` is optional; without it only the
+ * checks that don't need the page's own path run.
+ *
+ * It judges one string. A title with a " | Brand" tail is `titleHead`'s to
+ * cut, and the caller asks about the head: `isPageAddress(titleHead(title), path)`.
+ * Pure string logic, linear in the length of the input.
+ */
+export declare function isPageAddress(value: string | null | undefined, path?: string | null): boolean;
+/**
+ * Whether a stored title is a real name for the page at `path`: something is
+ * left once the pipes are set aside, and none of its pieces is a page's
+ * address (`isPageAddress`, given the page's path). It's the one rule for a
+ * title that gets printed whole, so whoever stores a name and whoever prints
+ * it can't disagree.
+ *
+ * Every piece is judged, the first and the last included, because a title
+ * with a pipe in it prints with its pipes: ":slug | Example Apartments" (a
+ * placeholder in front of a brand tail) and "Floor Plans | /floor-plans/x" (a
+ * path behind the name) are both refused, and so is the unspaced
+ * "Floor Plans|/floor-plans/x". A name with a pipe in it stays a name while
+ * every piece is text ("1 Bedroom | 1BR 1BA"). A title that's only pipes has
+ * no piece and isn't a name. Empty, whitespace-only, nullish and non-string
+ * values aren't names either.
+ *
+ * It judges the title it is given, brand tail and all. A writer cuts the tail
+ * first and asks about what it stores: `isPageName(titleHead(title), path)`.
+ * `path` is optional, as it is for `isPageAddress`. Pure string logic, linear
+ * in the length of the input.
+ */
+export declare function isPageName(title: string | null | undefined, path?: string | null): boolean;

package/dist/page-titles.js

@@ -118,7 +118,40 @@ function isRoutePlaceholder(value) {
   if (typeof value !== "string") return false;
   return value.split("/").some((segment) => PLACEHOLDER_TOKEN.test(segment.trim()));
 }
+var ABSOLUTE_URL = /^[a-z][a-z0-9+.-]*:\/\//i;
+var HOST_NAME = /^(?:[a-z0-9-]+\.)+[a-z]{2,}(?::\d{1,5})?$/i;
+function withoutOuterSlashes(value) {
+  let start = 0;
+  let end = value.length;
+  while (start < end && value[start] === "/") start++;
+  while (end > start && value[end - 1] === "/") end--;
+  return value.slice(start, end);
+}
+function isHostPath(value) {
+  const slash = value.indexOf("/");
+  if (slash < 0 || /\s/.test(value)) return false;
+  return HOST_NAME.test(value.slice(0, slash));
+}
+function isPageAddress(value, path) {
+  if (typeof value !== "string") return false;
+  const given = value.trim();
+  if (!given) return false;
+  if (given.startsWith("/") || ABSOLUTE_URL.test(given) || isHostPath(given) || isRoutePlaceholder(given)) return true;
+  if (typeof path !== "string") return false;
+  const own = withoutOuterSlashes(path.trim());
+  return withoutOuterSlashes(given) === own;
+}
+function pipePieces(title) {
+  return title.split("|").map((piece) => piece.trim()).filter(Boolean);
+}
+function isPageName(title, path) {
+  if (typeof title !== "string") return false;
+  const pieces = pipePieces(title);
+  return pieces.length > 0 && pieces.every((piece) => !isPageAddress(piece, path));
+}
 
+exports.isPageAddress = isPageAddress;
+exports.isPageName = isPageName;
 exports.isRoutePlaceholder = isRoutePlaceholder;
 exports.slugLabel = slugLabel;
 exports.titleHead = titleHead;

package/dist/page-titles.mjs

@@ -116,5 +116,36 @@ function isRoutePlaceholder(value) {
   if (typeof value !== "string") return false;
   return value.split("/").some((segment) => PLACEHOLDER_TOKEN.test(segment.trim()));
 }
+var ABSOLUTE_URL = /^[a-z][a-z0-9+.-]*:\/\//i;
+var HOST_NAME = /^(?:[a-z0-9-]+\.)+[a-z]{2,}(?::\d{1,5})?$/i;
+function withoutOuterSlashes(value) {
+  let start = 0;
+  let end = value.length;
+  while (start < end && value[start] === "/") start++;
+  while (end > start && value[end - 1] === "/") end--;
+  return value.slice(start, end);
+}
+function isHostPath(value) {
+  const slash = value.indexOf("/");
+  if (slash < 0 || /\s/.test(value)) return false;
+  return HOST_NAME.test(value.slice(0, slash));
+}
+function isPageAddress(value, path) {
+  if (typeof value !== "string") return false;
+  const given = value.trim();
+  if (!given) return false;
+  if (given.startsWith("/") || ABSOLUTE_URL.test(given) || isHostPath(given) || isRoutePlaceholder(given)) return true;
+  if (typeof path !== "string") return false;
+  const own = withoutOuterSlashes(path.trim());
+  return withoutOuterSlashes(given) === own;
+}
+function pipePieces(title) {
+  return title.split("|").map((piece) => piece.trim()).filter(Boolean);
+}
+function isPageName(title, path) {
+  if (typeof title !== "string") return false;
+  const pieces = pipePieces(title);
+  return pieces.length > 0 && pieces.every((piece) => !isPageAddress(piece, path));
+}
 
-export { isRoutePlaceholder, slugLabel, titleHead };
+export { isPageAddress, isPageName, isRoutePlaceholder, slugLabel, titleHead };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sonordev/contracts",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "description": "The rules Sonor's sites, APIs and dashboard share: popup blocks and site design tokens, site hosts, SEO page identity, title quality, llms.txt sanitizers, the forms honeypot, fleet heartbeats, slot content and signing, site cache tags, portfolio metrics, the house voice's contraction rule, how a proposal's site plan counts its pages, what separates an error page from a page's content, which stored JSON-LD is a template's unfilled placeholder, where prose splits into sentences, which Sonor records Signal reads into a project's knowledge and the address each one is stored under, what outbound email and text may claim about a business and whether a sent email arrived intact, what a segment of outreach is and who may turn one on, a page's own name taken from its title or its slug, which Broadcast card layouts and review compositions are drawn and what a retired one draws as, and what a publication's branding may hold. Pure functions, no dependencies.",
   "license": "MIT",
   "repository": {