@byline/host-tanstack-start 0.9.3

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

@@ -0,0 +1,313 @@
+/**
+ * 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 { useMemo, useState } from 'react'
+import { useRouterState } from '@tanstack/react-router'
+
+import type { ColumnDefinition, WorkflowStatus } from '@byline/core'
+import type { AnyCollectionSchemaTypes } from '@byline/core/zod-schemas'
+import { renderFormatted, StatusBadge } from '@byline/ui'
+import {
+  Container,
+  IconButton,
+  LoaderRing,
+  PlusIcon,
+  Search,
+  Section,
+  Select,
+  Table,
+} from '@infonomic/uikit/react'
+import cx from 'classnames'
+
+import { Link, useNavigate } from '../chrome/loose-router.js'
+import { RouterPager } from '../chrome/router-pager.js'
+import { TableHeadingCellSortable } from '../chrome/th-sortable.js'
+import { formatNumber } from '../chrome/utils.js'
+import styles from './list.module.css'
+
+/**
+ * Resolve a column value from a document, checking `fields` first (user-defined
+ * collection fields) then the root (metadata like status, updated_at).
+ */
+// biome-ignore lint/suspicious/noExplicitAny: collection rows are heterogeneous
+function getColumnValue(document: any, fieldName: string): any {
+  if (document.fields && fieldName in document.fields) {
+    return document.fields[fieldName]
+  }
+  return document[fieldName]
+}
+
+function Stats({ total }: { total: number }) {
+  const [showLoader, _] = useState(false)
+
+  if (showLoader) {
+    return (
+      <LoaderRing
+        className={cx('byline-coll-list-stats-loader', styles.statsLoader)}
+        size={24}
+        color="#666666"
+      />
+    )
+  }
+  return (
+    <span className={cx('byline-coll-list-stats', styles.stats)}>
+      {formatNumber(total as number, 0)}
+    </span>
+  )
+}
+
+function padRows(value: number) {
+  return Array.from({ length: value }).map((_, index) => (
+    <div
+      key={`empty-row-${
+        // biome-ignore lint/suspicious/noArrayIndexKey: we're okay here
+        index
+      }`}
+      className={cx('byline-coll-list-pad-row', styles.padRow)}
+    >
+      &nbsp;
+    </div>
+  ))
+}
+
+export const ListView = ({
+  data,
+  columns,
+  workflowStatuses,
+  useAsTitle,
+}: {
+  data: AnyCollectionSchemaTypes['ListType']
+  columns: ColumnDefinition[]
+  workflowStatuses?: WorkflowStatus[]
+  useAsTitle?: string
+}) => {
+  const navigate = useNavigate()
+  const location = useRouterState({ select: (s) => s.location })
+
+  // Memoized so Base UI's SelectRoot doesn't see a fresh items identity on
+  // every render — a non-stable items array combined with a controlled value
+  // trips an internal store sync loop (manifests as "Maximum update depth
+  // exceeded" inside SelectRoot after navigations that cause a re-render).
+  const statusItems = useMemo(
+    () => [
+      { value: '_all', label: 'All' },
+      ...(workflowStatuses?.map((ws) => ({ value: ws.name, label: ws.label ?? ws.name })) ?? []),
+    ],
+    [workflowStatuses]
+  )
+
+  const handleOnSearch = (query: string): void => {
+    if (query != null && query.length > 0) {
+      const params = structuredClone(location.search)
+      delete params.page
+      params.query = query
+      navigate({
+        to: '/admin/collections/$collection' as never,
+        params: { collection: data.included.collection.path },
+        search: params,
+      })
+    }
+  }
+
+  const handleOnClear = (): void => {
+    const params = structuredClone(location.search)
+    delete params.page
+    delete params.query
+    navigate({
+      to: '/admin/collections/$collection' as never,
+      params: { collection: data.included.collection.path },
+      search: params,
+    })
+  }
+
+  const handleOnStatusFilter = (value: string | null): void => {
+    if (typeof value !== 'string' || value.length === 0) return
+    const params = structuredClone(location.search)
+    delete params.page
+    if (value === '_all') {
+      delete params.status
+    } else {
+      params.status = value
+    }
+    navigate({
+      to: '/admin/collections/$collection' as never,
+      params: { collection: data.included.collection.path },
+      search: params,
+    })
+  }
+
+  function handleOnPageSizeChange(value: string | null): void {
+    if (typeof value !== 'string' || value.length === 0) return
+    const params = structuredClone(location.search)
+    delete params.page
+    params.page_size = Number.parseInt(value, 10)
+    navigate({
+      to: '/admin/collections/$collection' as never,
+      params: { collection: data.included.collection.path },
+      search: params,
+    })
+  }
+
+  return (
+    <Section>
+      <Container>
+        <div className={cx('byline-coll-list-head', styles.head)}>
+          <h1 className={cx('byline-coll-list-title', styles.title)}>
+            {data.included.collection.labels.plural as string}
+          </h1>
+          <Stats total={data?.meta.total} />
+          <IconButton
+            aria-label="Create New"
+            render={
+              <Link
+                to={'/admin/collections/$collection/create' as never}
+                params={{ collection: data.included.collection.path }}
+              />
+            }
+          >
+            <PlusIcon height="18px" width="18px" svgClassName="stroke-white" />
+          </IconButton>
+        </div>
+        <div className={cx('byline-coll-list-options', styles.options)}>
+          <Search
+            onSearch={handleOnSearch}
+            onClear={handleOnClear}
+            inputSize="sm"
+            placeholder="Search"
+            className={cx('byline-coll-list-search', styles.search)}
+          />
+
+          {workflowStatuses && workflowStatuses.length > 1 && (
+            <Select<string>
+              id="status_filter"
+              name="status_filter"
+              size="sm"
+              value={(location.search as { status?: string }).status ?? '_all'}
+              items={statusItems}
+              onValueChange={handleOnStatusFilter}
+            />
+          )}
+
+          <RouterPager
+            page={data?.meta.page}
+            count={data?.meta.totalPages}
+            showFirstButton
+            showLastButton
+            componentName="pagerTop"
+            aria-label="Top Pager"
+          />
+        </div>
+        <Table.Container className={cx('byline-coll-list-table-wrap', styles.tableWrap)}>
+          <Table>
+            <Table.Header>
+              <Table.Row>
+                {columns.map((column) => {
+                  return (
+                    <TableHeadingCellSortable
+                      key={String(column.fieldName)}
+                      fieldName={String(column.fieldName)}
+                      label={column.label}
+                      sortable={column.sortable}
+                      scope="col"
+                      align={column.align}
+                      className={column.className}
+                    />
+                  )
+                })}
+              </Table.Row>
+            </Table.Header>
+
+            <Table.Body>
+              {data?.docs?.map((document) => {
+                return (
+                  <Table.Row key={document.id}>
+                    {columns.map((column) => (
+                      <Table.Cell
+                        key={String(column.fieldName)}
+                        className={cx({
+                          'byline-coll-list-cell-right': column.align === 'right',
+                          [styles.cellRight]: column.align === 'right',
+                          'byline-coll-list-cell-center': column.align === 'center',
+                          [styles.cellCenter]: column.align === 'center',
+                        })}
+                      >
+                        {useAsTitle && column.fieldName === useAsTitle ? (
+                          <Link
+                            to={'/admin/collections/$collection/$id' as never}
+                            params={{
+                              collection: data.included.collection.path,
+                              id: document.id,
+                            }}
+                          >
+                            {column.formatter
+                              ? renderFormatted(
+                                  getColumnValue(document, column.fieldName as string),
+                                  document,
+                                  column.formatter
+                                )
+                              : (getColumnValue(document, column.fieldName as string) ?? '------')}
+                          </Link>
+                        ) : column.formatter ? (
+                          renderFormatted(
+                            getColumnValue(document, column.fieldName as string),
+                            document,
+                            column.formatter
+                          )
+                        ) : column.fieldName === 'status' && workflowStatuses ? (
+                          <StatusBadge
+                            status={document.status}
+                            workflowStatuses={workflowStatuses}
+                            hasPublishedVersion={document.hasPublishedVersion}
+                          />
+                        ) : (
+                          String(getColumnValue(document, column.fieldName as string) ?? '')
+                        )}
+                      </Table.Cell>
+                    ))}
+                  </Table.Row>
+                )
+              })}
+            </Table.Body>
+          </Table>
+          {padRows(6 - (data?.docs?.length ?? 0))}
+        </Table.Container>
+        <div
+          className={cx(
+            'byline-coll-list-options byline-coll-list-options-bottom',
+            styles.options,
+            styles.optionsBottom
+          )}
+        >
+          <Select<string>
+            containerClassName={cx('byline-coll-list-page-size', styles.pageSize)}
+            id="page_size"
+            name="page_size"
+            size="sm"
+            defaultValue="15"
+            items={[
+              { value: '15', label: '15' },
+              { value: '30', label: '30' },
+              { value: '50', label: '50' },
+              { value: '100', label: '100' },
+            ]}
+            onValueChange={handleOnPageSizeChange}
+          />
+          <RouterPager
+            smoothScrollToTop={true}
+            page={data?.meta.page}
+            count={data?.meta.totalPages}
+            showFirstButton
+            showLastButton
+            componentName="pagerBottom"
+            aria-label="Bottom Pager"
+          />
+        </div>
+      </Container>
+    </Section>
+  )
+}

package/src/admin-shell/collections/preview-link.tsx

@@ -0,0 +1,138 @@
+/**
+ * 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
+ */
+
+/**
+ * Per-document preview affordance for the admin shell.
+ *
+ * Renders an external-link icon that, when clicked:
+ *   1. Calls `enablePreviewModeFn()` to set the `byline_preview` cookie
+ *      on the admin's session — so the front-end host's viewer client
+ *      starts surfacing draft versions for this admin's subsequent
+ *      requests.
+ *   2. Opens the document's preview URL in a new tab via
+ *      `window.open(url, '_blank', 'noopener,noreferrer')`.
+ *
+ * The preview URL comes from `CollectionAdminConfig.preview.url(doc, ctx)`
+ * when configured; otherwise it falls back to the conventional
+ * `/${collectionPath}/${doc.path}`. When the configured `url(...)` returns
+ * `null` (missing slug, missing required relation, etc.), the icon is
+ * not rendered at all — there is no public URL meaningful for this
+ * document yet, so offering a preview link would just lead to a 404.
+ *
+ * The component does not load the document itself. Callers pass the
+ * already-loaded `doc` from their route loader. If `preview.populate`
+ * is configured, it's the loader's responsibility to apply that hint
+ * when fetching the document so `url(doc, ctx)` sees the resolved
+ * relation values it expects (e.g. `doc.fields.area?.document?.path`).
+ *
+ * Two-step "enable cookie then navigate" intentionally avoids the
+ * Payload-style `/routes/draft?url=...&secret=...` redirect handler:
+ * `enablePreviewModeFn()` is itself the gate (it requires a valid admin
+ * session before setting the cookie), so no shared secret needs to ride
+ * in the URL.
+ */
+
+import { useState } from 'react'
+
+import type { CollectionAdminConfig, PreviewDocument } from '@byline/core'
+import { ExternalLinkIcon, IconButton, useToastManager } from '@infonomic/uikit/react'
+import cx from 'classnames'
+
+import { enablePreviewModeFn } from '../../server-fns/preview/index.js'
+
+export interface PreviewLinkProps {
+  /** Collection path (e.g. `'news'`, `'pages'`). */
+  collectionPath: string
+  /** The loaded document — must include `id`, `path`, and `fields`. */
+  doc: PreviewDocument
+  /** Admin config for the collection. Read for `preview.url`. */
+  adminConfig?: CollectionAdminConfig
+  /** Current content locale (forwarded into `preview.url(doc, { locale })`). */
+  locale?: string
+  /** Optional className for the IconButton. */
+  className?: string
+}
+
+/**
+ * Resolve the preview URL for a doc against an admin config. Exported so
+ * other surfaces (list-row preview links in the future) can share the
+ * same fallback logic.
+ *
+ * Returns:
+ *   - `string`  → URL to open
+ *   - `null`    → no preview URL meaningful for this doc; hide affordance
+ */
+export function resolvePreviewUrl(
+  doc: PreviewDocument,
+  collectionPath: string,
+  adminConfig: CollectionAdminConfig | undefined,
+  locale: string | undefined
+): string | null {
+  if (adminConfig?.preview) {
+    return adminConfig.preview.url(doc, { locale })
+  }
+  // Default convention: collection lives at `/${collectionPath}/${path}`.
+  // Returns null when the doc has no path yet (unsaved, awaiting slug).
+  if (!doc.path) return null
+  return `/${collectionPath}/${doc.path}`
+}
+
+export const PreviewLink = ({
+  collectionPath,
+  doc,
+  adminConfig,
+  locale,
+  className,
+}: PreviewLinkProps) => {
+  const toastManager = useToastManager()
+  const [busy, setBusy] = useState(false)
+
+  const url = resolvePreviewUrl(doc, collectionPath, adminConfig, locale)
+  if (url == null) return null
+
+  const handleClick = async () => {
+    if (busy) return
+    setBusy(true)
+    try {
+      // Enable preview mode for the admin's browser session before opening
+      // the URL. The viewer client on the front-end host reads the cookie
+      // on subsequent requests and elevates the read context.
+      await enablePreviewModeFn()
+      // `noopener,noreferrer` so the opened tab can't reach back into
+      // the admin window via `window.opener`.
+      window.open(url, '_blank', 'noopener,noreferrer')
+    } catch (err) {
+      toastManager.add({
+        title: 'Preview',
+        description: `Could not enable preview mode: ${(err as Error).message}`,
+        data: {
+          intent: 'danger',
+          iconType: 'danger',
+          icon: true,
+          close: true,
+        },
+      })
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  return (
+    <IconButton
+      className={cx('byline-preview-link', className)}
+      size="xs"
+      variant="text"
+      disabled={busy}
+      onClick={handleClick}
+      aria-label="Open preview in new tab"
+      title="Preview"
+    >
+      <ExternalLinkIcon width="20px" height="20px" className="byline-preview-link-icon" />
+    </IconButton>
+  )
+}

package/src/admin-shell/collections/tanstack-navigation-guard.ts

@@ -0,0 +1,43 @@
+/**
+ * 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
+ */
+
+/**
+ * TanStack Router adapter for the framework-agnostic NavigationGuard interface.
+ *
+ * This file lives in `@byline/host-tanstack-start` (not in `@byline/ui`) because
+ * it depends on `@tanstack/react-router` — a framework-specific dependency.
+ */
+
+import { useCallback } from 'react'
+import { useBlocker } from '@tanstack/react-router'
+
+import type { NavigationGuardResult, UseNavigationGuard } from '@byline/ui'
+
+/**
+ * Navigation guard backed by TanStack Router's `useBlocker`.
+ *
+ * Blocks both in-app (soft) navigation and the browser's native `beforeunload`
+ * event when `shouldBlock` is `true`.
+ */
+export const useTanStackNavigationGuard: UseNavigationGuard = (shouldBlock) => {
+  const shouldBlockFn = useCallback(() => shouldBlock, [shouldBlock])
+
+  const blocker = useBlocker({
+    shouldBlockFn,
+    enableBeforeUnload: shouldBlock,
+    withResolver: true,
+  })
+
+  const result: NavigationGuardResult = {
+    isBlocked: blocker.status === 'blocked',
+    stay: () => blocker.reset?.(),
+    proceed: () => blocker.proceed?.(),
+  }
+
+  return result
+}

package/src/admin-shell/collections/view-menu.module.css

@@ -0,0 +1,60 @@
+/**
+ * ViewMenu — mini-nav bar for document-level views (Edit, History, API).
+ *
+ * Override handles:
+ *   .byline-view-menu        — outer flex row
+ *   .byline-view-menu-label  — locale/depth label (lg-only)
+ *   .byline-view-menu-button — primary view buttons (Edit/API)
+ *   .byline-view-menu-icon-button — history icon button
+ */
+
+.root,
+:global(.byline-view-menu) {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin-top: 0.5rem;
+  margin-bottom: 0.5rem;
+}
+
+.label,
+:global(.byline-view-menu-label) {
+  display: none;
+  color: var(--gray-400);
+  font-size: 0.75rem;
+  padding-top: 2px;
+}
+
+@media (min-width: 66rem) {
+  .label,
+  :global(.byline-view-menu-label) {
+    display: block;
+  }
+}
+
+.localeSelect,
+:global(.byline-view-menu-locale-select) {
+  min-width: 100px;
+  padding: 0.1rem 0;
+}
+
+.depthSelect,
+:global(.byline-view-menu-depth-select) {
+  min-width: 60px;
+}
+
+.iconButton,
+:global(.byline-view-menu-icon-button) {
+  min-width: 24px;
+}
+
+.iconButtonIcon,
+:global(.byline-view-menu-icon-button-icon) {
+  width: 1.25rem;
+  height: 1.25rem;
+}
+
+.button,
+:global(.byline-view-menu-button) {
+  min-width: 50px;
+}