@byline/cli 2.4.4 → 2.5.1

package/dist/templates/byline/server.config.ts

@@ -24,7 +24,10 @@ import { type BylineCore, initBylineCore } from '@byline/core'
 import { pgAdapter } from '@byline/db-postgres'
 import { createAdminStore } from '@byline/db-postgres/admin'
 import { getAdminBylineClient } from '@byline/host-tanstack-start/integrations/byline-client'
-import { lexicalEditorServer } from '@byline/richtext-lexical/server'
+import {
+  lexicalEditorEmbedServer,
+  lexicalEditorPopulateServer,
+} from '@byline/richtext-lexical/server'
 import { localStorageProvider } from '@byline/storage-local'
 
 import { i18n } from './i18n.js'
@@ -128,7 +131,10 @@ async function buildBylineCore(): Promise<BylineCore<AdminStore>> {
     // }),
     sessionProvider,
     fields: {
-      richText: { populate: lexicalEditorServer({ getClient: getAdminBylineClient }) },
+      richText: {
+        embed: lexicalEditorEmbedServer({ getClient: getAdminBylineClient }),
+        populate: lexicalEditorPopulateServer({ getClient: getAdminBylineClient }),
+      },
     },
   })
 

package/dist/templates/byline-examples/collections/pages/admin.tsx

@@ -119,29 +119,22 @@ export const PagesAdmin: CollectionAdminConfig = defineAdmin(Pages, {
   },
 
   /**
-   * Preview URL builder for live preview links. Returns a URL string (relative
-   * or absolute), or `null` to hide the preview affordance.
+   * Preview URL builder for live preview links. Delegates to the
+   * schema-side `Pages.buildDocumentPath` (the single source of truth
+   * for how a page composes into a public path — also driven by the
+   * richtext embed walker on internal-link nodes) and adds the request-
+   * locale prefix on top. Returns `null` to hide the preview affordance.
    *
-   * `doc.path` is the top-level slug (derived from `useAsPath`), not a field.
-   * Direct relations are auto-populated by the edit view (depth 1, picker
-   * projection) and appear under `doc.fields.<name>?.document`.
-   *
-   * @example
-   * preview: {
-   *   url: (doc, { locale }) => {
-   *     if (!doc.path) return null
-   *     const prefix = locale && locale !== 'en' ? `/${locale}` : ''
-   *     return `${prefix}/${doc.path}`
-   *   },
-   * }
+   * `doc.path` is the top-level slug (derived from `useAsPath`), not a
+   * field. Direct relations are auto-populated by the edit view (depth
+   * 1, picker projection) and appear under `doc.fields.<name>?.document`.
    */
   preview: {
     url: (doc, { locale }) => {
-      if (!doc.path) return null
+      const path = Pages.buildDocumentPath?.(doc, { collectionPath: Pages.path }) ?? null
+      if (path == null) return null
       const prefix = locale && locale !== i18n.interface.defaultLocale ? `/${locale}` : ''
-      const pathWithArea =
-        doc.fields?.area && doc.fields.area !== 'root' ? `${doc.fields.area}/${doc.path}` : doc.path
-      return `${prefix}/${pathWithArea}`
+      return `${prefix}${path}`
     },
   },
 

package/dist/templates/byline-examples/collections/pages/schema.ts

@@ -36,6 +36,26 @@ export const Pages = defineCollection({
   search: { fields: ['title'] },
   useAsTitle: 'title',
   useAsPath: 'title',
+  /**
+   * Pages live at the site root (no `/pages/` prefix) and may be nested
+   * under an `area` segment. Same composition rule used by the admin
+   * preview button (`admin.tsx` delegates to this) and the richtext
+   * embed walker that refreshes `document.path` on internal links.
+   *
+   * Returns a locale-agnostic root-relative path; the renderer prepends
+   * the locale at request time. Returns `null` when no slug exists yet
+   * (brand-new draft) so the embed walker / preview both fall back to
+   * "no link available" rather than producing a broken URL.
+   */
+  buildDocumentPath: (doc, _ctx) => {
+    if (!doc.path) return null
+    const area = doc.fields?.area
+    if (typeof area === 'string' && area !== 'root') {
+      return `/${area}/${doc.path}`
+    }
+    return `/${doc.path}`
+  },
+  linksInEditor: true,
   fields: [
     { name: 'title', label: 'Title', type: 'text', localized: true },
     {

package/dist/templates/byline-examples/fields/lexical-richtext-compact.ts

@@ -14,8 +14,8 @@
  * seeds (see `byline/server.config.ts`).
  *
  * **Constraint** — `editorConfig` baked into a schema can only override
- * **settings** (placeholder, toolbar UI flags, `embedRelationsOnSave`).
- * Extension references (TableExtension, AdmonitionExtension, etc.) are
+ * **settings** (placeholder, toolbar UI flags). Extension references
+ * (TableExtension, AdmonitionExtension, etc.) are
  * not JSON-safe and would break tsx-loaded seeds; per-field extension
  * removal goes through a client-side wrapper component registered via
  * `FieldAdminConfig.editor` — see `aiRichTextAdmin()` for the pattern.

package/dist/templates/byline-examples/server.config.ts

@@ -20,7 +20,10 @@ import { type BylineCore, initBylineCore } from '@byline/core'
 import { pgAdapter } from '@byline/db-postgres'
 import { createAdminStore } from '@byline/db-postgres/admin'
 import { getAdminBylineClient } from '@byline/host-tanstack-start/integrations/byline-client'
-import { lexicalEditorServer } from '@byline/richtext-lexical/server'
+import {
+  lexicalEditorEmbedServer,
+  lexicalEditorPopulateServer,
+} from '@byline/richtext-lexical/server'
 import { localStorageProvider } from '@byline/storage-local'
 
 // Import collection definitions directly from schema files — NOT the full
@@ -200,7 +203,10 @@ async function buildBylineCore(): Promise<BylineCore<AdminStore>> {
       // server config singleton, which is only populated *after*
       // `initBylineCore()` returns. Passing a factory defers resolution
       // to populate-call time so registration order here doesn't matter.
-      richText: { populate: lexicalEditorServer({ getClient: getAdminBylineClient }) },
+      richText: {
+        embed: lexicalEditorEmbedServer({ getClient: getAdminBylineClient }),
+        populate: lexicalEditorPopulateServer({ getClient: getAdminBylineClient }),
+      },
     },
   })
 

package/dist/templates/ui-byline/components/link/link-lexical.tsx

@@ -9,25 +9,53 @@ import type { Locale } from '@/ui/byline/types/i18n'
 
 // import { getPublicWebsiteUrl } from '@/utils/utils.framework.ts'
 
-export interface LinkAttributes {
-  linkType?: 'custom' | 'internal'
+interface BaseLinkAttributes {
   newTab?: boolean
   nofollow?: boolean
-  rel?: string
+  rel?: string | null
+}
+
+export interface CustomLinkAttributes extends BaseLinkAttributes {
+  linkType?: 'custom'
   url?: string
-  doc?: {
-    value: string
-    relationTo: string
-    data: {
-      id: string
-      title: string
-      slug: string
-      area: string
-      collectionAlias: string
-    }
+}
+
+/**
+ * Internal link to a Byline document. Mirrors `DocumentRelation` —
+ * `targetDocumentId` / `targetCollectionId` / `targetCollectionPath`
+ * flattened onto the attributes, plus a `document` bag carrying the
+ * canonical `{ title, path }` envelope embedded by the picker at write
+ * time and refreshed by the server-side write-time embed walker.
+ *
+ * `document.path` has dual meaning during migration:
+ *   - leading `/` — composed by `CollectionDefinition.buildDocumentPath`
+ *     (or the generic `/${collectionPath}/${slug}` fallback) and treated
+ *     as authoritative by this serializer.
+ *   - no leading `/` — bare slug from `byline_document_paths`, either
+ *     legacy data or a picker-time write that hasn't been through the
+ *     walker yet. The serializer applies the generic compose fallback
+ *     using `targetCollectionPath`.
+ *
+ * `document._resolved === false` means the most recent walker pass
+ * could not find the target document (deleted between picker and
+ * save / read). The serializer strips the `<a>` wrapper and renders
+ * children as plain text — persisted state is preserved so an editor
+ * can re-link later.
+ */
+export interface InternalLinkAttributes extends BaseLinkAttributes {
+  linkType: 'internal'
+  targetDocumentId: string
+  targetCollectionId: string
+  targetCollectionPath: string
+  document?: {
+    title?: string
+    path?: string
+    _resolved?: false
   }
 }
 
+export type LinkAttributes = CustomLinkAttributes | InternalLinkAttributes
+
 export type LinkType = 'internal' | 'custom'
 
 export interface LinkLexicalProps {
@@ -57,38 +85,55 @@ export function manageRel(input: string, action: 'add' | 'remove', value: string
   return result
 }
 
+// Hrefs we treat as "stays in the page / app" — skip URL parsing,
+// skip the external-link icon, don't force `target="_blank"`. `#anchor`
+// is an intra-page jump; empty hrefs would be inert placeholders but
+// `LinkLexicalSerializer` short-circuits those before reaching here.
+function isLocalHref(href: string): boolean {
+  if (href.length === 0) return true
+  if (href.startsWith('#')) return true
+  return ['tel:', 'mailto:', '/'].some((prefix) => href.startsWith(prefix))
+}
+
+/**
+ * Resolve the renderable href for a link node. Returns `''` when no
+ * usable href can be built — the serializer treats that as the signal
+ * to strip the `<a>` / `<LangLink>` wrapper and render children plain.
+ *
+ * Internal-link fallback chain (see docs/RICHTEXT.md):
+ *   1. `document._resolved === false` → strip wrapper.
+ *   2. `document.path` starts with `/` → use as-is (canonicalised by
+ *      the server-side embed walker via `buildDocumentPath`).
+ *   3. `document.path` is a bare slug + `targetCollectionPath` present
+ *      → generic compose `/${targetCollectionPath}/${path}`. Heal-on-
+ *      write fallback for legacy nodes and picker-time-but-not-yet-
+ *      walked sessions.
+ *   4. Neither — strip wrapper.
+ */
 function getHref(args: LinkAttributes): string {
   let href = ''
   const publicWebsiteUrl = '/' // getPublicWebsiteUrl()
-  const { linkType, url } = args
-
-  if ((linkType === 'custom' || linkType === undefined) && url != null) {
-    href = url
-  } else if (
-    linkType === 'internal' &&
-    args.doc?.relationTo != null &&
-    args.doc?.data?.slug != null
-  ) {
-    const collection = args.doc.relationTo
-    const { slug, area, collectionAlias } = args.doc.data
-    if (collectionAlias != null) {
-      // The alias might be for the root
-      if (collectionAlias.length === 0) {
-        href = `/${slug}`
-      } else {
-        href = `/${collectionAlias}/${slug}`
-      }
-    } else {
-      href = `/${collection}/${slug}`
-    }
 
-    if (area != null && area.length > 0 && area !== 'root') {
-      href = `/${area}${href}`
+  if (args.linkType === 'internal') {
+    // Step 1 — walker explicitly marked the target as missing.
+    if (args.document?._resolved === false) return ''
+
+    const path = args.document?.path
+    if (path != null && path.length > 0) {
+      if (path.startsWith('/')) {
+        // Step 2 — canonical path written by the embed walker.
+        href = path
+      } else if (args.targetCollectionPath) {
+        // Step 3 — bare slug, generic compose fallback.
+        href = `/${args.targetCollectionPath}/${path}`
+      }
+      // else: fall through to step 4 — empty href, wrapper stripped.
     }
+  } else if (args.url != null) {
+    href = args.url
   }
 
-  const hrefIsLocal = ['tel:', 'mailto:', '/'].some((prefix) => href.startsWith(prefix))
-  if (!hrefIsLocal) {
+  if (!isLocalHref(href)) {
     try {
       const objectURL = new URL(href)
       if (objectURL.origin === publicWebsiteUrl) {
@@ -126,7 +171,7 @@ function getAdditionalProps(
     additionalProps.target = '_blank'
   }
 
-  if (!href.startsWith('/')) {
+  if (!isLocalHref(href)) {
     additionalProps.target = '_blank'
   }
 
@@ -145,6 +190,16 @@ export function LinkLexicalSerializer({
   children,
 }: LinkLexicalProps): React.JSX.Element {
   const href = getHref(attributes)
+
+  // No usable href — render children plain (no anchor) so the public site
+  // never carries a broken `<a href="">`. Covers `_resolved: false` and
+  // every other empty-href branch of `getHref`. The admin editor reads
+  // `__attributes` directly via Lexical APIs, so the link node stays
+  // visible in the editor for re-linking.
+  if (href.length === 0) {
+    return <>{children}</>
+  }
+
   const additionalProps = getAdditionalProps(attributes, href)
 
   if (href.startsWith('/')) {
@@ -161,6 +216,21 @@ export function LinkLexicalSerializer({
       </LangLink>
     )
   }
+  // Local but not a router path (#anchor, tel:, mailto:): plain
+  // <a>, no external-link affordance.
+  if (isLocalHref(href)) {
+    return (
+      <a
+        href={href}
+        {...additionalProps}
+        className={cx(className, 'underline')}
+        onMouseEnter={onMouseEnter}
+        onMouseLeave={onMouseLeave}
+      >
+        {children}
+      </a>
+    )
+  }
   return (
     <a
       href={href}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/cli",
   "private": false,
   "license": "MPL-2.0",
-  "version": "2.4.4",
+  "version": "2.5.1",
   "engines": {
     "node": ">=20.9.0"
   },