@byline/admin 4.15.0 → 4.17.0

package/src/forms/form-renderer-submit.test.tsx

@@ -0,0 +1,194 @@
+/**
+ * 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
+ */
+
+import { act } from 'react'
+
+import { defineAdminConfig } from '@byline/core'
+import { adminTranslations } from '@byline/i18n/admin'
+import { I18nProvider } from '@byline/i18n/react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { BylineFieldServicesProvider } from '../fields/field-services-context'
+
+vi.mock('@byline/ui/react', async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>()
+  const Pass = ({ children }: any) => <div>{children}</div>
+  const Modal: any = ({ children, isOpen }: any) => (isOpen ? <div>{children}</div> : null)
+  Modal.Container = Pass
+  Modal.Header = Pass
+  Modal.Content = Pass
+  Modal.Actions = Pass
+  return {
+    ...actual,
+    Dropdown: {
+      Root: Pass,
+      Trigger: ({ children }: any) => <div data-testid="actions-trigger">{children}</div>,
+      Portal: Pass,
+      Content: Pass,
+      Item: ({ children, onClick }: any) => (
+        <div
+          onClick={onClick}
+          onKeyDown={(event) => {
+            if (event.key === 'Enter' || event.key === ' ') onClick?.(event)
+          }}
+          role="menuitem"
+          tabIndex={0}
+        >
+          {children}
+        </div>
+      ),
+      Separator: () => <hr />,
+    },
+    Modal,
+    Input: ({ name, value, onChange }: any) => (
+      <input name={name} value={value ?? ''} onChange={onChange} />
+    ),
+  }
+})
+
+;(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true
+
+defineAdminConfig({
+  i18n: {
+    admin: { defaultLocale: 'en', locales: ['en'] },
+    content: { defaultLocale: 'en', locales: ['en'] },
+  },
+  collections: [
+    {
+      path: 'pages',
+      labels: { singular: 'Page', plural: 'Pages' },
+      fields: [{ name: 'title', label: 'Title', type: 'text' }],
+    },
+  ],
+  slugifier: (value: string) => value.toLowerCase().trim().replace(/\s+/g, '-'),
+})
+
+const fieldServices = {
+  getCollectionDocuments: async () => ({ docs: [], total: 0 }),
+  uploadField: async () => ({}),
+} as any
+
+let container: HTMLDivElement
+let root: Root
+
+beforeEach(() => {
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  root = createRoot(container)
+})
+
+afterEach(() => {
+  act(() => {
+    root.unmount()
+  })
+  container.remove()
+})
+
+const renderInProvider = (element: React.ReactNode) => {
+  act(() => {
+    root.render(
+      <I18nProvider
+        bundle={adminTranslations({ locales: ['en'] })}
+        activeLocale="en"
+        defaultLocale="en"
+        localeDefinitions={[{ code: 'en', nativeName: 'English' }]}
+      >
+        <BylineFieldServicesProvider services={fieldServices}>
+          {element}
+        </BylineFieldServicesProvider>
+      </I18nProvider>
+    )
+  })
+}
+
+import { FormRenderer } from './form-renderer'
+
+const fields = [{ name: 'title', label: 'Title', type: 'text' as const }]
+
+const typeIntoTitle = (value: string) => {
+  const input = container.querySelector<HTMLInputElement>('input[name="title"]')
+  if (input == null) throw new Error('title input not found')
+  const setter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value')?.set
+  act(() => {
+    setter?.call(input, value)
+    input.dispatchEvent(new Event('input', { bubbles: true }))
+  })
+}
+
+const submitForm = () => {
+  const form = container.querySelector('form')
+  if (form == null) throw new Error('form not found')
+  act(() => {
+    form.requestSubmit()
+  })
+}
+
+describe('FormRenderer submit contract', () => {
+  const render = (props: Record<string, unknown>) =>
+    renderInProvider(<FormRenderer {...(props as any)} />)
+
+  const baseProps = {
+    mode: 'create' as const,
+    fields,
+    onCancel: () => {},
+    collectionPath: 'pages',
+  }
+
+  it('becomes dirty once a field is edited', () => {
+    render({ ...baseProps, onSubmit: async () => {} })
+    expect(container.textContent).toContain('Close')
+    typeIntoTitle('Hello')
+    expect(container.textContent).toContain('Cancel')
+  })
+
+  it('clears dirty state when onSubmit resolves', async () => {
+    const onSubmit = vi.fn(async () => {})
+    render({ ...baseProps, onSubmit })
+    typeIntoTitle('Hello')
+    submitForm()
+    await act(async () => {})
+    expect(onSubmit).toHaveBeenCalledTimes(1)
+    expect(container.textContent).toContain('Close')
+  })
+
+  it('preserves dirty state when onSubmit rejects', async () => {
+    const onSubmit = vi.fn(async () => {
+      throw new Error('save failed')
+    })
+    render({ ...baseProps, onSubmit })
+    typeIntoTitle('Hello')
+    submitForm()
+    await act(async () => {})
+    expect(onSubmit).toHaveBeenCalledTimes(1)
+    expect(container.textContent).toContain('Cancel')
+  })
+
+  it('ignores a second submit while the first is still in flight', async () => {
+    let release: () => void = () => {}
+    const gate = new Promise<void>((resolve) => {
+      release = resolve
+    })
+    const onSubmit = vi.fn(async () => {
+      await gate
+    })
+    render({ ...baseProps, onSubmit })
+    typeIntoTitle('Hello')
+    submitForm()
+    submitForm()
+    // Submission first awaits the field-hook pipeline, so flush that
+    // microtask before counting host calls. An immediate assertion here
+    // would observe zero calls and would not test duplicate suppression.
+    await act(async () => {})
+    expect(onSubmit).toHaveBeenCalledTimes(1)
+    await act(async () => {
+      release()
+    })
+    expect(onSubmit).toHaveBeenCalledTimes(1)
+  })
+})

package/src/forms/form-renderer.tsx

@@ -11,8 +11,8 @@
 import { type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from 'react'
 
 import type {
-  CollectionAdminConfig,
   Field,
+  FormAdminConfig,
   GroupDefinition,
   RowDefinition,
   TabSetDefinition,
@@ -82,7 +82,7 @@ export interface SystemFieldsSubmitPayload {
 export interface FormRendererProps {
   mode: 'create' | 'edit'
   fields: Field[]
-  onSubmit: (data: any) => void
+  onSubmit: (data: any) => void | Promise<void>
   onCancel: () => void
   onStatusChange?: (nextStatus: string) => Promise<void>
   onUnpublish?: () => Promise<void>
@@ -124,7 +124,7 @@ export interface FormRendererProps {
   workflowStatuses?: WorkflowStatus[]
   publishedVersion?: PublishedVersionInfo | null
   initialData?: Record<string, any>
-  adminConfig?: CollectionAdminConfig
+  adminConfig?: FormAdminConfig
   /**
    * Name of the schema field to render as the live form heading.
    * Sourced from `CollectionDefinition.useAsTitle` by the caller.
@@ -136,6 +136,20 @@ export interface FormRendererProps {
    * present the path widget renders in the sidebar.
    */
   useAsPath?: string
+  /**
+   * Whether the system path widget may render in the sidebar. Defaults to
+   * `true`, which preserves the historical behaviour of showing the widget
+   * whenever `useAsPath` is declared or the document envelope carries a
+   * `path`. Set `false` for a resource whose path is internal metadata and
+   * must never be presented or edited.
+   */
+  showPath?: boolean
+  /**
+   * Explicit form heading, used verbatim. Overrides both `useAsTitle`'s live
+   * value and the create/edit wording derived from `mode` — for a resource
+   * whose identity does not change when it is first materialised.
+   */
+  heading?: string
   /**
    * Opts the available-locales widget into the sidebar (below the path
    * widget). Sourced from `CollectionDefinition.advertiseLocales` by the
@@ -203,6 +217,8 @@ const FormContent = ({
   adminConfig,
   useAsTitle,
   useAsPath,
+  showPath = true,
+  heading,
   advertiseLocales,
   tree,
   headingLabel,
@@ -245,6 +261,8 @@ const FormContent = ({
   const [hasChanges, setHasChanges] = useState(hasChangesFn())
   const [statusBusy, setStatusBusy] = useState(false)
   const [isUploading, setIsUploading] = useState(false)
+  const submittingRef = useRef(false)
+  const [isSubmitting, setIsSubmitting] = useState(false)
   // Block-only "save first" guard. Set true when the editor triggers a
   // guarded action (status change, duplicate, copy-to-locale) while the form
   // is dirty — those actions operate on the saved version, so unsaved edits
@@ -336,7 +354,8 @@ const FormContent = ({
 
   // Live document heading — tracks the useAsTitle field as the user types
   const liveTitle = useFieldValue<string>(useAsTitle ?? '')
-  const heading =
+  const computedHeading =
+    heading ||
     liveTitle ||
     (headingLabel
       ? mode === 'create'
@@ -379,13 +398,27 @@ const FormContent = ({
     }
   }
 
-  // Emit the payload and optimistically clear dirty state (parity with the
-  // prior submit behaviour — the host surfaces failures via toast).
+  // Await the host handler. Resolution means the save succeeded and the clean
+  // baseline can be committed; rejection preserves dirty state so the editor
+  // does not lose work and the navigation guard keeps blocking. Host handlers
+  // that surface their own toast MUST rethrow afterwards.
+  // Re-entry guard lives in a ref so the callback identity does not change
+  // mid-flight; the mirrored state drives the Save button's disabled prop.
   const submitPayload = useCallback(
-    (payload: SystemFieldsSubmitPayload) => {
-      if (onSubmit && typeof onSubmit === 'function') {
-        onSubmit(payload)
+    async (payload: SystemFieldsSubmitPayload) => {
+      if (typeof onSubmit !== 'function') return
+      if (submittingRef.current) return
+      submittingRef.current = true
+      setIsSubmitting(true)
+      try {
+        await onSubmit(payload)
         resetHasChanges()
+      } catch {
+        // Intentionally swallowed here — the host has already reported the
+        // failure to the user. Dirty state is preserved by not resetting.
+      } finally {
+        submittingRef.current = false
+        setIsSubmitting(false)
       }
     },
     [onSubmit, resetHasChanges]
@@ -482,7 +515,7 @@ const FormContent = ({
         return
       }
 
-      submitPayload(payload)
+      await submitPayload(payload)
     })()
   }
 
@@ -582,7 +615,7 @@ const FormContent = ({
       aria-busy={isUploading}
     >
       <div className={cx('byline-form-heading-row', styles['heading-row'])}>
-        <h1 className={cx('byline-form-heading', styles.heading)}>{heading}</h1>
+        <h1 className={cx('byline-form-heading', styles.heading)}>{computedHeading}</h1>
         {/* Source-locale anchor indicator removed pending heading-layout work.
             To re-enable: render `<SourceLocaleBadge locale={sourceLocale} />`
             here from `initialData.sourceLocale` (mismatch-only is the intended
@@ -615,7 +648,7 @@ const FormContent = ({
             className={cx('byline-form-actions-button', styles['actions-button'])}
             size="sm"
             type="submit"
-            disabled={hasChanges === false || isUploading}
+            disabled={hasChanges === false || isUploading || isSubmitting}
           >
             {isUploading ? t('forms.actions.uploading') : t('common.actions.save')}
           </Button>
@@ -736,18 +769,19 @@ const FormContent = ({
           {layout.main.map((name) => renderItem(name))}
         </div>
         <div className={cx('byline-form-sidebar', styles.sidebar)}>
-          {(useAsPath ||
-            (typeof initialData?.path === 'string' && initialData.path.length > 0)) && (
-            <PathWidget
-              useAsPath={useAsPath}
-              collectionPath={collectionPath ?? ''}
-              defaultLocale={defaultLocale}
-              activeLocale={contentLocale}
-              mode={mode}
-              slugifier={pathSlugifier}
-              sourceLocked={pathSourceLocked}
-            />
-          )}
+          {showPath &&
+            (useAsPath ||
+              (typeof initialData?.path === 'string' && initialData.path.length > 0)) && (
+              <PathWidget
+                useAsPath={useAsPath}
+                collectionPath={collectionPath ?? ''}
+                defaultLocale={defaultLocale}
+                activeLocale={contentLocale}
+                mode={mode}
+                slugifier={pathSlugifier}
+                sourceLocked={pathSourceLocked}
+              />
+            )}
           {tree && mode === 'edit' && typeof initialData?.id === 'string' && (
             <TreePlacementWidget
               collectionPath={collectionPath ?? ''}
@@ -776,7 +810,7 @@ const FormContent = ({
           onConfirm={() => {
             const payload = pendingSystemFieldsSubmit
             setPendingSystemFieldsSubmit(null)
-            submitPayload(payload)
+            void submitPayload(payload)
           }}
         />
       )}

package/src/forms/tree-placement-widget.tsx

@@ -10,7 +10,7 @@
 
 import { useCallback, useEffect, useState } from 'react'
 
-import { getCollectionDefinition } from '@byline/core'
+import { getCollectionDefinition, isSingleton } from '@byline/core'
 import { useTranslation } from '@byline/i18n/react'
 import { Button } from '@byline/ui/react'
 import cx from 'clsx'
@@ -49,7 +49,8 @@ export const TreePlacementWidget = ({
 }: TreePlacementWidgetProps) => {
   const { t } = useTranslation('byline-admin')
   const { getTreeAncestors, getTreeParent, placeTreeNode } = useBylineFieldServices()
-  const targetDefinition = getCollectionDefinition(collectionPath)
+  const definition = getCollectionDefinition(collectionPath)
+  const targetDefinition = definition != null && !isSingleton(definition) ? definition : null
 
   const [parent, setParent] = useState<{ id: string; title: string } | null>(null)
   // Whether the document has an edge row at all. `false` = *unplaced* (no row);

package/src/forms/use-form-layout.ts

@@ -11,8 +11,8 @@
 import { useMemo } from 'react'
 
 import type {
-  CollectionAdminConfig,
   Field,
+  FormAdminConfig,
   GroupDefinition,
   LayoutDefinition,
   RowDefinition,
@@ -50,7 +50,7 @@ export interface FormLayout {
  * the `seen` set guards against a config that references a row/group cycle.
  */
 export function buildFieldToTabPath(
-  adminConfig: CollectionAdminConfig | undefined,
+  adminConfig: FormAdminConfig | undefined,
   fieldByName: Map<string, Field>,
   rowByName: Map<string, RowDefinition>,
   groupByName: Map<string, GroupDefinition>
@@ -90,7 +90,7 @@ export function buildFieldToTabPath(
  * Rebuilt only when `adminConfig` / `fields` change.
  */
 export function useFormLayout(
-  adminConfig: CollectionAdminConfig | undefined,
+  adminConfig: FormAdminConfig | undefined,
   fields: Field[]
 ): FormLayout {
   const fieldByName = useMemo(() => {

package/src/index.ts

@@ -36,5 +36,6 @@ export * from './modules/admin-activity/index.js'
 export * from './modules/admin-permissions/index.js'
 export * from './modules/admin-roles/index.js'
 export * from './modules/admin-users/index.js'
+export * from './modules/analytics/index.js'
 export * from './modules/auth/index.js'
 export type { AdminStore } from './store.js'

package/src/modules/analytics/abilities.ts

@@ -0,0 +1,33 @@
+/**
+ * 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
+ */
+
+import type { AbilityRegistry } from '@byline/auth'
+
+export const ANALYTICS_ABILITIES = {
+  read: 'analytics.read',
+  maintain: 'analytics.maintain',
+} as const
+
+export type AnalyticsAbilityKey = (typeof ANALYTICS_ABILITIES)[keyof typeof ANALYTICS_ABILITIES]
+
+export function registerAnalyticsAbilities(registry: AbilityRegistry): void {
+  registry.register({
+    key: ANALYTICS_ABILITIES.read,
+    label: 'Read analytics',
+    description: 'View installation-level page, visitor, download, referrer, and country totals.',
+    group: 'analytics',
+    source: 'admin',
+  })
+  registry.register({
+    key: ANALYTICS_ABILITIES.maintain,
+    label: 'Maintain analytics',
+    description: 'Delete retained analytics events and rebuild affected daily aggregates.',
+    group: 'analytics',
+    source: 'admin',
+  })
+}