@byline/host-tanstack-start 4.16.0 → 4.18.0

package/src/admin-shell/chrome/dashboard.test.tsx

@@ -0,0 +1,199 @@
+/**
+ * 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 React from 'react'
+import { act } from 'react'
+
+import { defineAdminConfig, defineSingleton, type MultiCollectionDefinition } from '@byline/core'
+import { createRoot } from 'react-dom/client'
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const abilityState = vi.hoisted(() => ({
+  isSuperAdmin: false,
+  abilities: [] as string[],
+}))
+
+vi.mock('../../integrations/abilities.jsx', () => ({
+  useAbilities: () => ({
+    isSuperAdmin: abilityState.isSuperAdmin,
+    abilities: abilityState.abilities,
+    has: () => false,
+    hasAny: () => false,
+  }),
+}))
+
+vi.mock('@byline/i18n/react', () => ({
+  useTranslation: () => ({
+    t: (key: string, values?: Record<string, string | number>) => {
+      if (key === 'dashboard.totalCount') return `${values?.count} total`
+      if (key === 'dashboard.collectionDescription') return `Manage ${values?.label}`
+      return key
+    },
+  }),
+}))
+
+vi.mock('@byline/ui/react', () => {
+  type Props = { children?: React.ReactNode; className?: string }
+  const element = (tag: keyof React.JSX.IntrinsicElements) =>
+    function Element({ children, ...props }: Props) {
+      const Component = tag
+      return <Component {...props}>{children}</Component>
+    }
+  const Card = element('article') as ReturnType<typeof element> & {
+    Header: ReturnType<typeof element>
+    Title: ReturnType<typeof element>
+    Description: ReturnType<typeof element>
+    Content: ReturnType<typeof element>
+  }
+  Card.Header = element('header')
+  Card.Title = element('h3')
+  Card.Description = element('p')
+  Card.Content = element('div')
+  return { Card, Container: element('div'), Section: element('section') }
+})
+
+vi.mock('./loose-router.js', () => ({
+  Link: ({
+    to = '',
+    params = {},
+    search: _search,
+    children,
+    ...props
+  }: React.AnchorHTMLAttributes<HTMLAnchorElement> & {
+    to?: string
+    params?: Record<string, string>
+    search?: unknown
+  }) => {
+    let href = to
+    for (const [name, value] of Object.entries(params)) {
+      href = href.replace(`$${name}`, value)
+    }
+    return (
+      <a href={href} {...props}>
+        {children}
+      </a>
+    )
+  },
+}))
+
+import { AdminDashboard } from './dashboard.js'
+
+const articles: MultiCollectionDefinition = {
+  path: 'articles',
+  labels: { singular: 'Article', plural: 'Articles' },
+  fields: [{ name: 'title', label: 'Title', type: 'text' }],
+  showStats: true,
+}
+
+const settings = defineSingleton({
+  path: 'site-settings',
+  label: 'Site settings',
+  fields: [{ name: 'title', label: 'Title', type: 'text' }],
+})
+
+function renderDashboard(statsMap: Record<string, Array<{ status: string; count: number }>> = {}) {
+  const container = document.createElement('div')
+  document.body.append(container)
+  const root = createRoot(container)
+  act(() => root.render(<AdminDashboard statsMap={statsMap} />))
+  return {
+    container,
+    dispose() {
+      act(() => root.unmount())
+      container.remove()
+    },
+  }
+}
+
+describe('AdminDashboard document resources', () => {
+  beforeAll(() => {
+    ;(
+      globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }
+    ).IS_REACT_ACT_ENVIRONMENT = true
+  })
+
+  afterAll(() => {
+    delete (globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean })
+      .IS_REACT_ACT_ENVIRONMENT
+  })
+
+  beforeEach(() => {
+    abilityState.isSuperAdmin = false
+    abilityState.abilities = []
+    defineAdminConfig({
+      routes: { admin: '/internal/cms' },
+      collections: [articles, settings],
+      admin: [
+        { slug: articles.path, group: 'content' },
+        { singleton: true, slug: settings.path, group: 'content' },
+      ],
+      collectionGroups: [{ name: 'content', label: 'Content' }],
+      i18n: {
+        admin: { defaultLocale: 'en', locales: [] },
+        content: { defaultLocale: 'en', locales: [] },
+      },
+    })
+  })
+
+  it('shows a singleton only for its kind-aware read ability', () => {
+    abilityState.abilities = ['singletons.site-settings.read']
+    const allowed = renderDashboard()
+    expect(allowed.container.textContent).toContain('Site settings')
+    expect(allowed.container.textContent).not.toContain('Articles')
+    allowed.dispose()
+
+    abilityState.abilities = ['collections.site-settings.read']
+    const staleNamespace = renderDashboard()
+    expect(staleNamespace.container.textContent).not.toContain('Site settings')
+    staleNamespace.dispose()
+  })
+
+  it('shows both resource kinds to a super admin in registry order', () => {
+    abilityState.isSuperAdmin = true
+    const view = renderDashboard({ articles: [{ status: 'draft', count: 3 }] })
+
+    const titles = [...view.container.querySelectorAll('.byline-dashboard-title-text')].map(
+      (element) => element.textContent
+    )
+    expect(titles).toEqual(['Articles', 'Site settings'])
+    expect(view.container.querySelector('.byline-dashboard-group-heading')?.textContent).toBe(
+      'Content'
+    )
+    view.dispose()
+  })
+
+  it('links a singleton under the custom admin base without collection stats', () => {
+    abilityState.isSuperAdmin = true
+    const view = renderDashboard({
+      articles: [{ status: 'draft', count: 3 }],
+      'site-settings': [{ status: 'published', count: 99 }],
+    })
+
+    const link = view.container.querySelector<HTMLAnchorElement>(
+      'a[href="/internal/cms/singletons/site-settings"]'
+    )
+    const card = link?.closest('article')
+    expect(link).not.toBeNull()
+    expect(card?.querySelector('.byline-dashboard-stat-tile')).toBeNull()
+    expect(card?.querySelector('.byline-dashboard-title-meta')).toBeNull()
+    expect(card?.textContent).not.toContain('99')
+    expect(card?.textContent?.match(/Manage Site settings/g)).toHaveLength(1)
+    expect(
+      view.container.querySelector('a[href="/internal/cms/collections/articles"]')
+    ).not.toBeNull()
+    expect(view.container.querySelector('.byline-dashboard-stat-tile')).not.toBeNull()
+    view.dispose()
+  })
+
+  it('hides an update-only singleton role from the dashboard', () => {
+    abilityState.abilities = ['singletons.site-settings.update']
+    const view = renderDashboard()
+    expect(view.container.textContent).not.toContain('Site settings')
+    view.dispose()
+  })
+})

package/src/admin-shell/chrome/dashboard.tsx

@@ -6,12 +6,13 @@
  * Copyright (c) Infonomic Company Limited
  */
 
-import type { CollectionDefinition, WorkflowStatus } from '@byline/core'
+import type { MultiCollectionDefinition, SingletonDefinition, WorkflowStatus } from '@byline/core'
 import {
   filterReadableCollections,
   getAdminConfig,
   getWorkflowStatuses,
   groupCollectionsForAdmin,
+  isSingleton,
 } from '@byline/core'
 import { useTranslation } from '@byline/i18n/react'
 import { Card, Container, Section } from '@byline/ui/react'
@@ -68,7 +69,7 @@ function CollectionCard({
   collection,
   stats,
 }: {
-  collection: CollectionDefinition
+  collection: MultiCollectionDefinition
   stats: CollectionStatusCount[] | undefined
 }) {
   const { t } = useTranslation('byline-admin')
@@ -134,6 +135,35 @@ function CollectionCard({
   )
 }
 
+function SingletonCard({ singleton }: { singleton: SingletonDefinition }) {
+  const { t } = useTranslation('byline-admin')
+  const destination = getAdminRoutePath('singletons', '$singleton')
+  const params = { singleton: singleton.path }
+
+  return (
+    <Card>
+      <Link
+        to={destination}
+        params={params}
+        className={cx('byline-dashboard-card-link', styles.cardLink)}
+      >
+        <Card.Header>
+          <div className={cx('byline-dashboard-card-header', styles.cardHeader)}>
+            <Card.Title className={cx('byline-dashboard-card-title', styles.cardTitle)}>
+              <span className={cx('byline-dashboard-title-text', styles.titleText)}>
+                {singleton.label}
+              </span>
+            </Card.Title>
+            <Card.Description className="muted">
+              {t('dashboard.collectionDescription', { label: singleton.label })}
+            </Card.Description>
+          </div>
+        </Card.Header>
+      </Link>
+    </Card>
+  )
+}
+
 interface AdminDashboardProps {
   statsMap: Record<string, CollectionStatusCount[]>
 }
@@ -173,13 +203,17 @@ export function AdminDashboard({ statsMap }: AdminDashboardProps) {
               </h2>
             )}
             <div className={cx('byline-dashboard-grid', styles.grid)}>
-              {bucket.collections.map((collection) => (
-                <CollectionCard
-                  key={collection.path}
-                  collection={collection}
-                  stats={statsMap[collection.path]}
-                />
-              ))}
+              {bucket.collections.map((resource) =>
+                isSingleton(resource) ? (
+                  <SingletonCard key={resource.path} singleton={resource} />
+                ) : (
+                  <CollectionCard
+                    key={resource.path}
+                    collection={resource}
+                    stats={statsMap[resource.path]}
+                  />
+                )
+              )}
             </div>
           </section>
         ))}

package/src/admin-shell/chrome/router-pager.tsx

@@ -6,6 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 
+import { useCallback } from 'react'
 import { useRouterState } from '@tanstack/react-router'
 
 import type { PaginationProps } from '@byline/ui/react'
@@ -18,6 +19,7 @@ import {
 } from '@byline/ui/react'
 
 import { Link } from './loose-router.js'
+import { scrollWindowToTop } from './scroll-to-top.js'
 
 interface RouterPageProps extends PaginationProps {
   smoothScrollToTop?: boolean
@@ -27,6 +29,13 @@ interface RouterPageProps extends PaginationProps {
  * A convenience pager wrapped around uikit's Pagination with `asChild`
  * targets that delegate to TanStack Router's `<Link>`. `asChild` merges
  * the existing button styles into the rendered Link.
+ *
+ * `smoothScrollToTop` is for a pager sitting *below* a long list: turning a
+ * page there should carry the reader back to the top rather than leaving them
+ * at the foot of a fresh page. It suppresses the router's own instant
+ * `resetScroll` and animates instead — so the component owes an actual
+ * scroll, which was the missing half: the flag disabled the reset and put
+ * nothing in its place, so a bottom pager did not scroll at all.
  */
 export function RouterPager({
   className,
@@ -36,6 +45,14 @@ export function RouterPager({
 }: RouterPageProps): React.JSX.Element {
   const location = useRouterState({ select: (s) => s.location })
 
+  // Fires alongside navigation rather than after it: the scroll and the new
+  // page load run together, so the list is in place by the time the reader
+  // arrives at the top.
+  const handleScrollToTop = useCallback(() => {
+    if (smoothScrollToTop !== true) return
+    scrollWindowToTop()
+  }, [smoothScrollToTop])
+
   return (
     <Pagination variant="dashboard" {...rest}>
       <Pagination.Root className={className} ariaLabel={ariaLabel}>
@@ -51,6 +68,7 @@ export function RouterPager({
                   ) : (
                     <Link
                       resetScroll={smoothScrollToTop !== true}
+                      onClick={handleScrollToTop}
                       to={location.pathname as never}
                       search={params}
                     />
@@ -76,6 +94,7 @@ export function RouterPager({
                   ) : (
                     <Link
                       resetScroll={smoothScrollToTop !== true}
+                      onClick={handleScrollToTop}
                       to={location.pathname as never}
                       search={params}
                     />
@@ -103,6 +122,7 @@ export function RouterPager({
                   ) : (
                     <Link
                       resetScroll={smoothScrollToTop !== true}
+                      onClick={handleScrollToTop}
                       to={location.pathname as never}
                       search={params}
                     />
@@ -130,6 +150,7 @@ export function RouterPager({
                   ) : (
                     <Link
                       resetScroll={smoothScrollToTop !== true}
+                      onClick={handleScrollToTop}
                       to={location.pathname as never}
                       search={params}
                     />
@@ -156,6 +177,7 @@ export function RouterPager({
                   ) : (
                     <Link
                       resetScroll={smoothScrollToTop !== true}
+                      onClick={handleScrollToTop}
                       to={location.pathname as never}
                       search={params}
                     />

package/src/admin-shell/chrome/scroll-to-top.test.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { scrollWindowToTop } from './scroll-to-top.js'
+
+function mockReducedMotion(matches: boolean) {
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn((query: string) => ({ matches, media: query })) as unknown as typeof window.matchMedia
+  )
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  vi.restoreAllMocks()
+})
+
+describe('scrollWindowToTop', () => {
+  it('scrolls to the top of the page', () => {
+    const scrollTo = vi.fn()
+    vi.stubGlobal('scrollTo', scrollTo)
+    mockReducedMotion(false)
+
+    scrollWindowToTop()
+
+    expect(scrollTo).toHaveBeenCalledWith({ top: 0, behavior: 'smooth' })
+  })
+
+  it('skips the animation when the reader asks for reduced motion', () => {
+    const scrollTo = vi.fn()
+    vi.stubGlobal('scrollTo', scrollTo)
+    mockReducedMotion(true)
+
+    scrollWindowToTop()
+
+    // Still goes to the top — only the travel is dropped.
+    expect(scrollTo).toHaveBeenCalledWith({ top: 0, behavior: 'auto' })
+  })
+
+  /** Older browsers and some test environments have no `matchMedia`. */
+  it('still scrolls when matchMedia is unavailable', () => {
+    const scrollTo = vi.fn()
+    vi.stubGlobal('scrollTo', scrollTo)
+    vi.stubGlobal('matchMedia', undefined)
+
+    expect(() => scrollWindowToTop()).not.toThrow()
+    expect(scrollTo).toHaveBeenCalledWith({ top: 0, behavior: 'smooth' })
+  })
+})

package/src/admin-shell/chrome/scroll-to-top.ts

@@ -0,0 +1,28 @@
+/**
+ * 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
+ */
+
+/**
+ * Return the reader to the top of the page.
+ *
+ * Separate from `RouterPager` so the behaviour can be asserted without
+ * mounting a router. `smoothScrollToTop` suppresses TanStack's instant
+ * `resetScroll` in favour of an animated one, which makes a missing
+ * implementation silent — the page simply does not move. That is what
+ * happened to every pager carrying the flag.
+ *
+ * Honours `prefers-reduced-motion`: those readers still arrive at the top,
+ * without the travel.
+ */
+export function scrollWindowToTop(): void {
+  if (typeof window === 'undefined') return
+
+  // `matchMedia` is absent in some test and server-ish environments; treating
+  // that as "no preference expressed" keeps the scroll working either way.
+  const prefersReducedMotion = window.matchMedia?.('(prefers-reduced-motion: reduce)').matches
+  window.scrollTo({ top: 0, behavior: prefersReducedMotion === true ? 'auto' : 'smooth' })
+}

package/src/admin-shell/collections/api.tsx

@@ -6,7 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 
-import type { CollectionDefinition } from '@byline/core'
+import type { MultiCollectionDefinition } from '@byline/core'
 import type { AnyCollectionSchemaTypes } from '@byline/core/zod-schemas'
 import { useTranslation } from '@byline/i18n/react'
 import { Container, Section } from '@byline/ui/react'
@@ -32,7 +32,7 @@ export const ApiView = ({
   contentLocales,
   defaultContentLocale,
 }: {
-  collectionDefinition: CollectionDefinition
+  collectionDefinition: MultiCollectionDefinition
   initialData: AnyCollectionSchemaTypes['UpdateType']
   /** Currently active locale from the route search param (undefined → all). */
   locale?: string

package/src/admin-shell/collections/create.tsx

@@ -9,7 +9,7 @@
 import { useState } from 'react'
 
 import { FormRenderer } from '@byline/admin/react'
-import type { CollectionAdminConfig, CollectionDefinition } from '@byline/core'
+import type { CollectionAdminConfig, MultiCollectionDefinition } from '@byline/core'
 import { useTranslation } from '@byline/i18n/react'
 import { Container, Section, useToastManager } from '@byline/ui/react'
 
@@ -30,7 +30,7 @@ export const CreateView = ({
   initialData,
   from,
 }: {
-  collectionDefinition: CollectionDefinition
+  collectionDefinition: MultiCollectionDefinition
   adminConfig?: CollectionAdminConfig
   // biome-ignore lint/suspicious/noExplicitAny: shape is collection-specific
   initialData?: Record<string, any>
@@ -105,6 +105,10 @@ export const CreateView = ({
         status: 'failed',
         message: description,
       })
+
+      // Rethrow so FormRenderer keeps the form dirty. The toast above has
+      // already told the editor what went wrong.
+      throw err
     }
   }
 

package/src/admin-shell/collections/edit.tsx

@@ -9,7 +9,7 @@
 import { useState } from 'react'
 
 import { FormRenderer } from '@byline/admin/react'
-import type { CollectionAdminConfig, CollectionDefinition } from '@byline/core'
+import type { CollectionAdminConfig, MultiCollectionDefinition } from '@byline/core'
 import {
   getDefaultStatus,
   getWorkflow,
@@ -56,7 +56,7 @@ export const EditView = ({
   defaultContentLocale,
   returnSearch,
 }: {
-  collectionDefinition: CollectionDefinition
+  collectionDefinition: MultiCollectionDefinition
   adminConfig?: CollectionAdminConfig
   initialData: AnyCollectionSchemaTypes['UpdateType']
   locale?: string
@@ -623,6 +623,10 @@ export const EditView = ({
       })
 
       setEditState({ status: 'failed', message: description })
+
+      // Rethrow so FormRenderer keeps the form dirty. The toast above has
+      // already told the editor what went wrong.
+      throw err
     }
   }
 

package/src/admin-shell/collections/history.module.css

@@ -1,5 +1,5 @@
 /**
- * HistoryView — list of past versions for a collection document.
+ * Shared version-history presentation for collection documents and singletons.
  *
  * Override handles:
  *   .byline-coll-history-head     — title + view-menu row