@byline/richtext-lexical 6.4.0 → 6.6.0

package/src/field/extensions/link/link-target-fields.tsx

@@ -0,0 +1,275 @@
+'use client'
+
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * The "where does this point?" sub-form, shared by the link modal and the
+ * inline-image modal.
+ *
+ * Purely presentational — every decision lives in `link-target-state.ts`,
+ * which is where the rules are tested. This file owns the markup, the
+ * picker's open/closed state, and nothing else.
+ *
+ * `idPrefix` is required rather than defaulted: two of these can be
+ * mounted in one document (an image modal over a link modal), and
+ * duplicate element ids break the `Label`/`htmlFor` association that
+ * screen readers depend on.
+ */
+
+import type * as React from 'react'
+import { useMemo, useState } from 'react'
+
+import { RelationPicker } from '@byline/admin/react'
+import type { MultiCollectionDefinition } from '@byline/core'
+import { getCollectionDefinition, isSingleton } from '@byline/core'
+import {
+  Button,
+  Checkbox,
+  CloseIcon,
+  EditIcon,
+  IconButton,
+  Input,
+  Label,
+  RadioGroup,
+  RadioGroupItem,
+  Select,
+  type SelectValue,
+} from '@byline/ui/react'
+
+import type { LinkTargetState } from './link-target-state'
+
+import './link-target-fields.css'
+
+export interface LinkTargetFieldsProps {
+  idPrefix: string
+  state: LinkTargetState
+  onChange: (next: LinkTargetState) => void
+  /** Collections with `linksInEditor: true`. Empty disables the picker. */
+  linkable: MultiCollectionDefinition[]
+  /** Offer a "no link" choice. See `LinkTargetOptions.allowNone`. */
+  allowNone: boolean
+  /** Validation message from `validateLinkTarget`, if the form was submitted. */
+  error?: string | null
+  /** Label above the kind radio. */
+  legend?: string
+}
+
+export const LinkTargetFields: React.FC<LinkTargetFieldsProps> = ({
+  idPrefix,
+  state,
+  onChange,
+  linkable,
+  allowNone,
+  error,
+  legend = 'Link',
+}) => {
+  const [pickerOpen, setPickerOpen] = useState(false)
+
+  const targetDefinition = state.targetCollection
+    ? getCollectionDefinition(state.targetCollection)
+    : null
+  const targetDef: MultiCollectionDefinition | null =
+    targetDefinition != null && !isSingleton(targetDefinition) ? targetDefinition : null
+
+  const collectionItems: SelectValue<string>[] = useMemo(
+    () => linkable.map((c) => ({ label: c.labels.singular, value: c.path })),
+    [linkable]
+  )
+
+  const pickedLabel: string | null = useMemo(() => {
+    if (state.kind !== 'internal' || !state.picked) return null
+    const title = state.picked.document?.title
+    if (typeof title === 'string' && title.length > 0) return title
+    const pickedDefinition = getCollectionDefinition(state.picked.targetCollectionPath)
+    const pickedDef =
+      pickedDefinition != null && !isSingleton(pickedDefinition) ? pickedDefinition : null
+    const short = state.picked.targetDocumentId.slice(0, 8)
+    return `${pickedDef?.labels.singular ?? state.picked.targetCollectionPath} · ${short}…`
+  }, [state.kind, state.picked])
+
+  const handlePickerSelect = (selection: {
+    targetDocumentId: string
+    targetCollectionId: string
+    record?: Record<string, any>
+  }) => {
+    setPickerOpen(false)
+    const targetCollection = state.targetCollection as string
+    // Normalise the picked record into a small `{ title, path }` envelope —
+    // everything a renderer needs to build a link without a round-trip.
+    // `useAsTitle` is always in the picker projection; `path` is top-level
+    // metadata on every list response.
+    const titleField = getCollectionDefinition(targetCollection)?.useAsTitle
+    const title = titleField ? selection.record?.fields?.[titleField] : undefined
+    const path = selection.record?.path
+    const document: Record<string, any> = {}
+    if (typeof title === 'string' && title.length > 0) document.title = title
+    if (typeof path === 'string' && path.length > 0) document.path = path
+    onChange({
+      ...state,
+      picked: {
+        targetDocumentId: selection.targetDocumentId,
+        targetCollectionId: selection.targetCollectionId,
+        targetCollectionPath: targetCollection,
+        document: Object.keys(document).length > 0 ? document : undefined,
+      },
+    })
+  }
+
+  return (
+    <>
+      <div className="flex flex-col gap-3">
+        <Label
+          id={`${idPrefix}-kind-label`}
+          htmlFor={`${idPrefix}-kind`}
+          className="text-sm font-medium"
+          label={legend}
+        />
+        <RadioGroup
+          id={`${idPrefix}-kind`}
+          name={`${idPrefix}-kind`}
+          aria-labelledby={`${idPrefix}-kind-label`}
+          direction="row"
+          value={state.kind}
+          onValueChange={(value) => onChange({ ...state, kind: value as LinkTargetState['kind'] })}
+        >
+          {allowNone && (
+            <RadioGroupItem id={`${idPrefix}-kind-none`} value="none" label="No link" />
+          )}
+          {linkable.length > 0 && (
+            <RadioGroupItem id={`${idPrefix}-kind-internal`} value="internal" label="Document" />
+          )}
+          <RadioGroupItem id={`${idPrefix}-kind-custom`} value="custom" label="Custom URL" />
+        </RadioGroup>
+
+        {state.kind === 'custom' && (
+          <Input
+            id={`${idPrefix}-url`}
+            name="url"
+            label="URL"
+            placeholder="https://example.com or /path"
+            value={state.url}
+            error={error != null}
+            errorText={error ?? undefined}
+            onChange={(e) => onChange({ ...state, url: e.target.value })}
+          />
+        )}
+
+        {state.kind === 'internal' && (
+          <div className="flex flex-col gap-3">
+            {linkable.length > 1 && (
+              <div>
+                <Label
+                  id={`${idPrefix}-collection-label`}
+                  htmlFor={`${idPrefix}-collection`}
+                  className="mb-1"
+                  label="Target collection"
+                />
+                <Select<string>
+                  size="sm"
+                  items={collectionItems}
+                  placeholder="Target collection"
+                  value={state.targetCollection ?? undefined}
+                  onValueChange={(value) => {
+                    if (value == null) return
+                    // Browsing other collections is exploratory — the
+                    // current pick survives until the picker replaces it.
+                    onChange({ ...state, targetCollection: value })
+                  }}
+                />
+              </div>
+            )}
+
+            <div>
+              <Label
+                id={`${idPrefix}-document-label`}
+                htmlFor={`${idPrefix}-document`}
+                className="mb-1"
+                label="Target document"
+              />
+              {/*
+                Frame → tile → icon actions, matching the admin relation
+                field. A chosen document is a summary line with edit and
+                remove icons, not a text button whose label changes; an
+                empty one is a single outlined select button.
+              */}
+              <div className="byline-link-target-frame">
+                {state.picked ? (
+                  <div className="byline-link-target-tile">
+                    <span className="byline-link-target-summary">
+                      <span className="byline-link-target-kind">
+                        {targetDef?.labels.singular ?? state.picked.targetCollectionPath}
+                      </span>
+                      <span className="byline-link-target-value">{pickedLabel}</span>
+                    </span>
+                    <span className="byline-link-target-actions">
+                      <IconButton
+                        id={`${idPrefix}-document`}
+                        type="button"
+                        intent="noeffect"
+                        size="xs"
+                        aria-label={`Change ${targetDef?.labels.singular ?? 'document'}`}
+                        onClick={() => setPickerOpen(true)}
+                        disabled={!state.targetCollection}
+                      >
+                        <EditIcon width="15px" height="15px" />
+                      </IconButton>
+                      <IconButton
+                        type="button"
+                        intent="noeffect"
+                        size="xs"
+                        aria-label={`Remove ${targetDef?.labels.singular ?? 'document'}`}
+                        onClick={() => onChange({ ...state, picked: null })}
+                      >
+                        <CloseIcon width="15px" height="15px" />
+                      </IconButton>
+                    </span>
+                  </div>
+                ) : (
+                  <Button
+                    id={`${idPrefix}-document`}
+                    size="xs"
+                    variant="outlined"
+                    intent="noeffect"
+                    type="button"
+                    onClick={() => setPickerOpen(true)}
+                    disabled={!state.targetCollection}
+                  >
+                    {`Select ${targetDef?.labels.singular ?? 'document'}`}
+                  </Button>
+                )}
+              </div>
+            </div>
+
+            {error && <span className="text-xs text-red-400">{error}</span>}
+          </div>
+        )}
+
+        {state.kind !== 'none' && (
+          <Checkbox
+            id={`${idPrefix}-new-tab`}
+            name="newTab"
+            label="Open in new tab"
+            checked={state.newTab}
+            onCheckedChange={(checked) => onChange({ ...state, newTab: checked === true })}
+          />
+        )}
+      </div>
+
+      {state.kind === 'internal' && state.targetCollection && (
+        <RelationPicker
+          targetCollectionPath={state.targetCollection}
+          targetDefinition={targetDef}
+          isOpen={pickerOpen}
+          onSelect={handlePickerSelect}
+          onDismiss={() => setPickerOpen(false)}
+        />
+      )}
+    </>
+  )
+}

package/src/field/extensions/link/link-target-state.test.node.ts

@@ -0,0 +1,197 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * The link-target form's state machine, extracted from `LinkModal` so both
+ * it and the inline-image modal drive the same rules — and so those rules
+ * are testable without rendering React (this repo carries no React
+ * testing library; the JSX shell is verified in the browser).
+ *
+ * Two callers with one asymmetry: a `LinkNode` always has a target, so
+ * `allowNone` is false there. An inline image's target is optional, so
+ * `allowNone` is true and `toLinkAttributes` can return undefined — which
+ * is how an editor removes a link.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import { fromLinkAttributes, toLinkAttributes, validateLinkTarget } from './link-target-state'
+import type { DocumentRelation } from '../../nodes/document-relation'
+import type { LinkAttributes } from '.'
+
+const linkable = [
+  { path: 'pages', labels: { singular: 'Page', plural: 'Pages' } },
+  { path: 'posts', labels: { singular: 'Post', plural: 'Posts' } },
+] as any[]
+
+const picked: DocumentRelation = {
+  targetDocumentId: 'doc-1',
+  targetCollectionId: 'coll-pages',
+  targetCollectionPath: 'pages',
+  document: { title: 'About Us', path: '/pages/about' },
+}
+
+const internalLink: LinkAttributes = {
+  linkType: 'internal',
+  newTab: false,
+  targetDocumentId: 'doc-1',
+  targetCollectionId: 'coll-pages',
+  targetCollectionPath: 'pages',
+  document: { title: 'About Us', path: '/pages/about' },
+}
+
+const customLink: LinkAttributes = {
+  linkType: 'custom',
+  url: 'https://example.com/report',
+  newTab: true,
+}
+
+/** The empty state is reached through the module's one entry point. */
+const empty = (linkable: any[], options: { allowNone: boolean }) =>
+  fromLinkAttributes(undefined, linkable as never, options)
+
+describe('the starting state', () => {
+  it('starts on "none" when the caller allows an absent target', () => {
+    expect(empty(linkable, { allowNone: true }).kind).toBe('none')
+  })
+
+  it('starts on "internal" when a target is required and collections are linkable', () => {
+    expect(empty(linkable, { allowNone: false }).kind).toBe('internal')
+  })
+
+  it('falls back to "custom" when no collection opts into the editor picker', () => {
+    expect(empty([], { allowNone: false }).kind).toBe('custom')
+  })
+
+  it('seeds the picker onto the first linkable collection', () => {
+    expect(empty(linkable, { allowNone: false }).targetCollection).toBe('pages')
+  })
+})
+
+describe('fromLinkAttributes', () => {
+  it('reads an absent link as "none" when that is allowed', () => {
+    expect(fromLinkAttributes(undefined, linkable, { allowNone: true }).kind).toBe('none')
+  })
+
+  it('loads a custom URL', () => {
+    const state = fromLinkAttributes(customLink, linkable, { allowNone: true })
+    expect(state.kind).toBe('custom')
+    expect(state.url).toBe('https://example.com/report')
+    expect(state.newTab).toBe(true)
+  })
+
+  it('loads an internal relation and points the picker at its collection', () => {
+    const state = fromLinkAttributes(internalLink, linkable, { allowNone: true })
+    expect(state.kind).toBe('internal')
+    expect(state.picked).toEqual(picked)
+    expect(state.targetCollection).toBe('pages')
+  })
+
+  // LinkModal's existing behaviour: the toolbar inserts a placeholder link
+  // with `https://`, which means "the user has not chosen yet" — so prefer
+  // the document picker rather than showing a URL box pre-filled with junk.
+  it.each(['', 'https://'])(
+    'treats the placeholder url %j as undecided and prefers the picker',
+    (url) => {
+      const state = fromLinkAttributes({ linkType: 'custom', url }, linkable, { allowNone: false })
+      expect(state.kind).toBe('internal')
+      expect(state.url).toBe('')
+    }
+  )
+
+  it('does not surface the placeholder url in the input', () => {
+    const state = fromLinkAttributes({ linkType: 'custom', url: 'https://' }, [], {
+      allowNone: false,
+    })
+    expect(state.kind).toBe('custom')
+    expect(state.url).toBe('')
+  })
+})
+
+describe('toLinkAttributes', () => {
+  it('returns undefined for "none" — this is how a link is removed', () => {
+    const state = empty(linkable, { allowNone: true })
+    expect(toLinkAttributes(state)).toBeUndefined()
+  })
+
+  it('builds a custom link', () => {
+    const state = {
+      ...empty([], { allowNone: true }),
+      kind: 'custom' as const,
+      url: 'https://example.com/report',
+      newTab: true,
+    }
+    expect(toLinkAttributes(state)).toEqual(customLink)
+  })
+
+  it('builds an internal link carrying the picked relation envelope', () => {
+    const state = {
+      ...empty(linkable, { allowNone: true }),
+      kind: 'internal' as const,
+      picked,
+      newTab: false,
+    }
+    expect(toLinkAttributes(state)).toEqual(internalLink)
+  })
+
+  it('returns undefined for an internal selection with nothing picked', () => {
+    const state = {
+      ...empty(linkable, { allowNone: true }),
+      kind: 'internal' as const,
+    }
+    expect(toLinkAttributes(state)).toBeUndefined()
+  })
+
+  it.each([customLink, internalLink])('round-trips %#', (link) => {
+    expect(toLinkAttributes(fromLinkAttributes(link, linkable, { allowNone: true }))).toEqual(link)
+  })
+})
+
+describe('validateLinkTarget', () => {
+  it('accepts "none"', () => {
+    expect(validateLinkTarget(empty(linkable, { allowNone: true }))).toBeNull()
+  })
+
+  it.each(['https://example.com', '/docs/getting-started', 'mailto:a@example.com'])(
+    'accepts %s as a custom target',
+    (url) => {
+      const state = {
+        ...empty([], { allowNone: true }),
+        kind: 'custom' as const,
+        url,
+      }
+      expect(validateLinkTarget(state)).toBeNull()
+    }
+  )
+
+  it('rejects an empty custom URL', () => {
+    const state = {
+      ...empty([], { allowNone: true }),
+      kind: 'custom' as const,
+      url: '',
+    }
+    expect(validateLinkTarget(state)).toBeTruthy()
+  })
+
+  it('rejects an internal selection with no document picked', () => {
+    const state = {
+      ...empty(linkable, { allowNone: true }),
+      kind: 'internal' as const,
+    }
+    expect(validateLinkTarget(state)).toBeTruthy()
+  })
+
+  it('accepts an internal selection once a document is picked', () => {
+    const state = {
+      ...empty(linkable, { allowNone: true }),
+      kind: 'internal' as const,
+      picked,
+    }
+    expect(validateLinkTarget(state)).toBeNull()
+  })
+})

package/src/field/extensions/link/link-target-state.ts

@@ -0,0 +1,158 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * The state machine behind "where does this link point?" — shared by the
+ * link modal and the inline-image modal so both offer the same choice of
+ * a Byline document or an arbitrary URL, with the same validation.
+ *
+ * React-free on purpose. The JSX shell lives in `link-target-fields.tsx`;
+ * everything that decides anything lives here, where it can be tested
+ * without a DOM.
+ *
+ * The one asymmetry between callers is `allowNone`. A `LinkNode` exists
+ * only because it has a target, so its form always resolves to a link. An
+ * inline image's target is optional, so its form adds a "no link" choice
+ * and `toLinkAttributes` may return `undefined` — which is precisely how
+ * an editor removes a link that is already there.
+ */
+
+import type { MultiCollectionDefinition } from '@byline/core'
+
+import { validateUrl } from '../../utils/url'
+import type { DocumentRelation } from '../../nodes/document-relation'
+import type { LinkAttributes } from '.'
+
+export interface LinkTargetState {
+  /** Narrow with `LinkTargetState['kind']` rather than a separate alias. */
+  kind: 'none' | 'custom' | 'internal'
+  /** Custom-URL text. Meaningful only when `kind === 'custom'`. */
+  url: string
+  newTab: boolean
+  /**
+   * Which collection the picker is currently pointed at — UI state only,
+   * and deliberately independent of `picked.targetCollectionPath` so the
+   * user can browse other collections without losing their selection.
+   */
+  targetCollection: string | null
+  /** The chosen document. Meaningful only when `kind === 'internal'`. */
+  picked: DocumentRelation | null
+}
+
+export interface LinkTargetOptions {
+  /** Whether "no link at all" is a valid outcome. */
+  allowNone: boolean
+}
+
+/**
+ * A link the toolbar inserted as a placeholder, before the editor has
+ * chosen anything. Shown as an empty form rather than a URL box pre-filled
+ * with `https://`.
+ */
+function isPlaceholderUrl(url: string | undefined): boolean {
+  return url == null || url === '' || url === 'https://'
+}
+
+/**
+ * The starting state for a form with nothing chosen yet. Module-private:
+ * `fromLinkAttributes(undefined, …)` returns exactly this, so callers have
+ * one way in rather than two that must agree.
+ */
+function emptyLinkTargetState(
+  linkable: MultiCollectionDefinition[],
+  options: LinkTargetOptions
+): LinkTargetState {
+  const firstLinkable = linkable[0]?.path ?? null
+  const kind: LinkTargetState['kind'] = options.allowNone
+    ? 'none'
+    : linkable.length > 0
+      ? 'internal'
+      : 'custom'
+  return {
+    kind,
+    url: '',
+    newTab: false,
+    targetCollection: firstLinkable,
+    picked: null,
+  }
+}
+
+export function fromLinkAttributes(
+  link: LinkAttributes | undefined,
+  linkable: MultiCollectionDefinition[],
+  options: LinkTargetOptions
+): LinkTargetState {
+  const base = emptyLinkTargetState(linkable, options)
+  if (link == null) return base
+
+  if (link.linkType === 'internal') {
+    const picked: DocumentRelation = {
+      targetDocumentId: link.targetDocumentId,
+      targetCollectionId: link.targetCollectionId,
+      targetCollectionPath: link.targetCollectionPath,
+      document: link.document,
+    }
+    return {
+      ...base,
+      kind: 'internal',
+      newTab: link.newTab ?? false,
+      targetCollection: picked.targetCollectionPath || base.targetCollection,
+      picked,
+    }
+  }
+
+  // Custom. An undecided placeholder prefers the document picker when any
+  // collection offers one; otherwise it stays on the (empty) URL field.
+  const placeholder = isPlaceholderUrl(link.url)
+  const kind: LinkTargetState['kind'] = placeholder && linkable.length > 0 ? 'internal' : 'custom'
+  return {
+    ...base,
+    kind,
+    url: placeholder ? '' : (link.url ?? ''),
+    newTab: link.newTab ?? false,
+  }
+}
+
+/**
+ * Collapse the form back to a `LinkAttributes`, or `undefined` when there
+ * is no usable target. Callers that require a link should run
+ * `validateLinkTarget` first — this function reports "nothing to store"
+ * rather than "the user made a mistake".
+ */
+export function toLinkAttributes(state: LinkTargetState): LinkAttributes | undefined {
+  if (state.kind === 'none') return undefined
+  if (state.kind === 'internal') {
+    if (state.picked == null) return undefined
+    return {
+      linkType: 'internal',
+      newTab: state.newTab,
+      targetDocumentId: state.picked.targetDocumentId,
+      targetCollectionId: state.picked.targetCollectionId,
+      targetCollectionPath: state.picked.targetCollectionPath,
+      document: state.picked.document,
+    }
+  }
+  if (state.url.length === 0) return undefined
+  return { linkType: 'custom', url: state.url, newTab: state.newTab }
+}
+
+/** Returns a human-readable problem, or `null` when the form is usable. */
+export function validateLinkTarget(state: LinkTargetState): string | null {
+  if (state.kind === 'none') return null
+  if (state.kind === 'internal') {
+    return state.picked == null ? 'Pick a target document' : null
+  }
+  if (state.url.length === 0) {
+    return 'Enter a URL or a root-relative path starting with /'
+  }
+  // Root-relative paths bypass `validateUrl`, which expects a scheme.
+  if (!state.url.startsWith('/') && !validateUrl(state.url)) {
+    return 'Enter a valid URL or a root-relative path starting with /'
+  }
+  return null
+}