@byline/host-tanstack-start 0.9.3

package/src/routes/create-collection-api-route.tsx

@@ -0,0 +1,111 @@
+/**
+ * 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 { createFileRoute, notFound } from '@tanstack/react-router'
+
+import type { CollectionDefinition } from '@byline/core'
+import { getCollectionDefinition } from '@byline/core'
+import { z } from 'zod'
+
+import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js'
+import { ApiView } from '../admin-shell/collections/api.js'
+import { getCollectionDocument } from '../server-fns/collections/index.js'
+import type { ContentLocaleOption } from '../admin-shell/collections/view-menu.js'
+
+const searchSchema = z.object({
+  locale: z.string().optional(),
+  /**
+   * Populate depth for relation fields. Capped at 3 to avoid runaway
+   * fan-out in the admin preview. Programmatic callers via
+   * `@byline/client` can go deeper.
+   */
+  depth: z.coerce.number().int().min(0).max(3).optional(),
+})
+
+interface CollectionApiOpts {
+  contentLocales: ReadonlyArray<ContentLocaleOption>
+  defaultContentLocale: string
+}
+
+export function createCollectionApiRoute(path: string, opts: CollectionApiOpts) {
+  // biome-ignore lint/suspicious/noExplicitAny: dynamic path bypasses route-tree typing
+  const Route: any = createFileRoute(path as never)({
+    validateSearch: searchSchema,
+    loaderDeps: ({ search }: { search: z.infer<typeof searchSchema> }) => ({
+      locale: search.locale,
+      depth: search.depth,
+    }),
+    loader: async ({
+      params,
+      deps,
+    }: {
+      params: { collection: string; id: string }
+      deps: { locale?: string; depth?: number }
+    }) => {
+      const collectionDef = getCollectionDefinition(params.collection)
+      if (!collectionDef) {
+        throw notFound()
+      }
+
+      // 'all' is now always explicit in the URL when the user picks it.
+      // No locale param means the user hasn't made a selection yet — default
+      // to the content default locale (same as History and Edit behaviours).
+      const resolvedLocale = deps.locale ?? opts.defaultContentLocale
+      const data = await getCollectionDocument(
+        params.collection,
+        params.id,
+        resolvedLocale,
+        deps.depth
+      )
+
+      if (!data) {
+        throw notFound()
+      }
+
+      return data
+    },
+    staleTime: 0,
+    gcTime: 0,
+    shouldReload: true,
+    component: function CollectionApiComponent() {
+      const data = Route.useLoaderData()
+      const { collection, id } = Route.useParams() as { collection: string; id: string }
+      const { locale, depth } = Route.useSearch() as z.infer<typeof searchSchema>
+      const collectionDef = getCollectionDefinition(collection) as CollectionDefinition
+
+      return (
+        <>
+          <BreadcrumbsClient
+            breadcrumbs={[
+              { label: 'Dashboard', href: `/admin` },
+              { label: collectionDef.labels.plural, href: `/admin/collections/${collection}` },
+              {
+                label: 'Edit',
+                href: `/admin/collections/${collection}/${id}`,
+              },
+              {
+                label: 'API',
+                href: `/admin/collections/${collection}/${id}/api`,
+              },
+            ]}
+          />
+          <ApiView
+            collectionDefinition={collectionDef}
+            initialData={data}
+            locale={locale}
+            depth={depth}
+            contentLocales={opts.contentLocales}
+            defaultContentLocale={opts.defaultContentLocale}
+          />
+        </>
+      )
+    },
+  })
+
+  return Route
+}

package/src/routes/create-collection-create-route.tsx

@@ -0,0 +1,66 @@
+/**
+ * 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 { createFileRoute, notFound } from '@tanstack/react-router'
+
+import type { CollectionDefinition } from '@byline/core'
+import {
+  buildInitialDataFromFields,
+  getCollectionAdminConfig,
+  getCollectionDefinition,
+} from '@byline/core'
+
+import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js'
+import { CreateView } from '../admin-shell/collections/create.js'
+
+export function createCollectionCreateRoute(path: string) {
+  // biome-ignore lint/suspicious/noExplicitAny: dynamic path bypasses route-tree typing
+  const Route: any = createFileRoute(path as never)({
+    loader: async ({
+      params,
+    }: {
+      params: { collection: string }
+      // biome-ignore lint/suspicious/noExplicitAny: collection-specific shape
+    }): Promise<{ initialData: any }> => {
+      const collectionDef = getCollectionDefinition(params.collection)
+      if (!collectionDef) {
+        throw notFound()
+      }
+      const initialData = await buildInitialDataFromFields(collectionDef.fields, {
+        data: {},
+        now: () => new Date(),
+      })
+      return { initialData }
+    },
+    component: function CollectionCreateComponent() {
+      const { collection } = Route.useParams() as { collection: string }
+      // biome-ignore lint/suspicious/noExplicitAny: collection-specific shape
+      const { initialData } = Route.useLoaderData() as { initialData: any }
+      const collectionDef = getCollectionDefinition(collection) as CollectionDefinition
+      const adminConfig = getCollectionAdminConfig(collection)
+      return (
+        <>
+          <BreadcrumbsClient
+            breadcrumbs={[
+              { label: 'Dashboard', href: '/admin' },
+              { label: collectionDef.labels.plural, href: `/admin/collections/${collection}` },
+              { label: 'Create', href: `/admin/collections/${collection}/create` },
+            ]}
+          />
+          <CreateView
+            collectionDefinition={collectionDef}
+            adminConfig={adminConfig ?? undefined}
+            initialData={initialData}
+          />
+        </>
+      )
+    },
+  })
+
+  return Route
+}

package/src/routes/create-collection-edit-route.tsx

@@ -0,0 +1,102 @@
+/**
+ * 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 { createFileRoute, notFound } from '@tanstack/react-router'
+
+import type { CollectionDefinition } from '@byline/core'
+import { getCollectionAdminConfig, getCollectionDefinition } from '@byline/core'
+import { z } from 'zod'
+
+import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js'
+import { EditView } from '../admin-shell/collections/edit.js'
+import { getCollectionDocument } from '../server-fns/collections/index.js'
+import type { ContentLocaleOption } from '../admin-shell/collections/view-menu.js'
+
+const searchSchema = z.object({
+  locale: z.string().optional(),
+})
+
+interface CollectionEditOpts {
+  contentLocales: ReadonlyArray<ContentLocaleOption>
+  defaultContentLocale: string
+}
+
+export function createCollectionEditRoute(path: string, opts: CollectionEditOpts) {
+  // biome-ignore lint/suspicious/noExplicitAny: dynamic path bypasses route-tree typing
+  const Route: any = createFileRoute(path as never)({
+    validateSearch: searchSchema,
+    loaderDeps: ({ search }: { search: z.infer<typeof searchSchema> }) => ({
+      locale: search.locale,
+    }),
+    loader: async ({
+      params,
+      deps,
+    }: {
+      params: { collection: string; id: string }
+      deps: { locale?: string }
+    }) => {
+      const collectionDef = getCollectionDefinition(params.collection)
+      if (!collectionDef) {
+        throw notFound()
+      }
+
+      // Auto-populate direct relation fields (depth 1) so the edit form's
+      // relation-summary tiles render with target data (category name, media
+      // thumbnail, etc.) on first paint. Projection is derived from each
+      // target's `CollectionAdminConfig.picker` columns.
+      const data = await getCollectionDocument(
+        params.collection,
+        params.id,
+        deps.locale,
+        undefined,
+        true
+      )
+
+      if (!data) {
+        throw notFound()
+      }
+
+      return data
+    },
+    staleTime: 0,
+    gcTime: 0,
+    shouldReload: true,
+    component: function CollectionEditComponent() {
+      const data = Route.useLoaderData()
+      const { collection, id } = Route.useParams() as { collection: string; id: string }
+      const { locale } = Route.useSearch() as z.infer<typeof searchSchema>
+      const collectionDef = getCollectionDefinition(collection) as CollectionDefinition
+      const adminConfig = getCollectionAdminConfig(collection)
+
+      return (
+        <>
+          <BreadcrumbsClient
+            breadcrumbs={[
+              { label: 'Dashboard', href: `/admin` },
+              { label: collectionDef.labels.plural, href: `/admin/collections/${collection}` },
+              {
+                label: 'Edit',
+                href: `/admin/collections/${collection}/${id}`,
+              },
+            ]}
+          />
+          <EditView
+            collectionDefinition={collectionDef}
+            adminConfig={adminConfig ?? undefined}
+            initialData={data}
+            locale={locale}
+            contentLocales={opts.contentLocales}
+            defaultContentLocale={opts.defaultContentLocale}
+          />
+        </>
+      )
+    },
+  })
+
+  return Route
+}

package/src/routes/create-collection-history-route.tsx

@@ -0,0 +1,130 @@
+/**
+ * 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 { createFileRoute, notFound } from '@tanstack/react-router'
+
+import type { CollectionDefinition } from '@byline/core'
+import {
+  getCollectionAdminConfig,
+  getCollectionDefinition,
+  getWorkflowStatuses,
+} from '@byline/core'
+import { z } from 'zod'
+
+import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js'
+import { HistoryView } from '../admin-shell/collections/history.js'
+import {
+  getCollectionDocument,
+  getCollectionDocumentHistory,
+} from '../server-fns/collections/index.js'
+import type { ContentLocaleOption } from '../admin-shell/collections/view-menu.js'
+
+const searchSchema = z.object({
+  page: z.coerce.number().min(1).optional(),
+  page_size: z.coerce.number().max(100).optional(),
+  order: z.string().optional(),
+  desc: z.coerce.boolean().optional(),
+  locale: z.string().optional(),
+})
+
+interface CollectionHistoryOpts {
+  contentLocales: ReadonlyArray<ContentLocaleOption>
+  defaultContentLocale: string
+}
+
+export function createCollectionHistoryRoute(path: string, opts: CollectionHistoryOpts) {
+  // biome-ignore lint/suspicious/noExplicitAny: dynamic path bypasses route-tree typing
+  const Route: any = createFileRoute(path as never)({
+    validateSearch: searchSchema,
+    loaderDeps: ({ search }: { search: z.infer<typeof searchSchema> }) => ({
+      page: search.page,
+      page_size: search.page_size,
+      order: search.order,
+      desc: search.desc,
+      locale: search.locale,
+    }),
+    loader: async ({
+      params,
+      deps,
+    }: {
+      params: { collection: string; id: string }
+      deps: {
+        page?: number
+        page_size?: number
+        order?: string
+        desc?: boolean
+        locale?: string
+      }
+    }) => {
+      const collectionDef = getCollectionDefinition(params.collection)
+      if (!collectionDef) {
+        throw notFound()
+      }
+
+      const [history, currentDocument] = await Promise.all([
+        getCollectionDocumentHistory({
+          data: {
+            collection: params.collection,
+            id: params.id,
+            params: {
+              page: deps.page,
+              page_size: deps.page_size,
+              order: deps.order,
+              desc: deps.desc,
+              locale: deps.locale,
+            },
+          },
+        }),
+        // Fetch the current document with the same locale (or 'all') so diffs
+        // compare the same shape as what the user is viewing.
+        getCollectionDocument(params.collection, params.id, deps.locale ?? 'all'),
+      ])
+
+      return { history, currentDocument }
+    },
+    staleTime: 0,
+    gcTime: 0,
+    shouldReload: true,
+    component: function CollectionHistoryComponent() {
+      const { history, currentDocument } = Route.useLoaderData()
+      const { collection } = Route.useParams() as { collection: string; id: string }
+      const collectionDef = getCollectionDefinition(collection) as CollectionDefinition
+      const adminConfig = getCollectionAdminConfig(collection)
+
+      return (
+        <>
+          <BreadcrumbsClient
+            breadcrumbs={[
+              { label: 'Dashboard', href: `/admin` },
+              { label: collectionDef.labels.plural, href: `/admin/collections/${collection}` },
+              {
+                label: 'Edit',
+                href: `/admin/collections/${collection}/${Route.useParams().id}`,
+              },
+              {
+                label: 'History',
+                href: `/admin/collections/${collection}/${Route.useParams().id}/history`,
+              },
+            ]}
+          />
+          <HistoryView
+            collectionDefinition={collectionDef}
+            workflowStatuses={getWorkflowStatuses(collectionDef)}
+            adminConfig={adminConfig ?? undefined}
+            data={history}
+            currentDocument={currentDocument as Record<string, unknown> | null}
+            contentLocales={opts.contentLocales}
+            defaultContentLocale={opts.defaultContentLocale}
+          />
+        </>
+      )
+    },
+  })
+
+  return Route
+}

package/src/routes/create-collection-list-route.tsx

@@ -0,0 +1,175 @@
+/**
+ * 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 { useEffect, useRef } from 'react'
+import { createFileRoute, notFound } from '@tanstack/react-router'
+
+import type { CollectionDefinition } from '@byline/core'
+import {
+  getCollectionAdminConfig,
+  getCollectionDefinition,
+  getWorkflowStatuses,
+} from '@byline/core'
+import { useToastManager } from '@infonomic/uikit/react'
+import { z } from 'zod'
+
+import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js'
+import { useNavigate } from '../admin-shell/chrome/loose-router.js'
+import { ListView } from '../admin-shell/collections/list.js'
+import { getCollectionDocuments } from '../server-fns/collections/index.js'
+
+const searchSchema = z.object({
+  page: z.coerce.number().min(1).optional(),
+  page_size: z.coerce.number().max(100).optional(),
+  order: z.string().optional(),
+  desc: z.coerce.boolean().optional(),
+  query: z.string().optional(),
+  locale: z.string().optional(),
+  status: z.string().optional(),
+  action: z.enum(['created']).optional(),
+})
+
+export function createCollectionListRoute(path: string) {
+  // biome-ignore lint/suspicious/noExplicitAny: dynamic path bypasses route-tree typing
+  const Route: any = createFileRoute(path as never)({
+    validateSearch: searchSchema,
+    loaderDeps: ({ search }: { search: z.infer<typeof searchSchema> }) => ({
+      page: search.page,
+      page_size: search.page_size,
+      order: search.order,
+      desc: search.desc,
+      query: search.query,
+      locale: search.locale,
+      status: search.status,
+    }),
+    loader: async ({
+      params,
+      deps,
+    }: {
+      params: { collection: string }
+      deps: {
+        page?: number
+        page_size?: number
+        order?: string
+        desc?: boolean
+        query?: string
+        locale?: string
+        status?: string
+      }
+    }) => {
+      const collectionDef = getCollectionDefinition(params.collection)
+      if (!collectionDef) {
+        throw notFound()
+      }
+
+      // Derive the field names the list view needs from the admin column config.
+      // This lets findDocuments query only the relevant store tables.
+      const adminConfig = getCollectionAdminConfig(params.collection)
+      const fields = adminConfig?.columns
+        ?.map((c) => String(c.fieldName))
+        .filter((name) => collectionDef.fields.some((f) => f.name === name))
+
+      const data = await getCollectionDocuments({
+        data: {
+          collection: params.collection,
+          params: {
+            page: deps.page,
+            page_size: deps.page_size,
+            order: deps.order,
+            desc: deps.desc,
+            query: deps.query,
+            locale: deps.locale,
+            status: deps.status,
+            fields,
+          },
+        },
+      })
+
+      return data
+    },
+    component: function CollectionListComponent() {
+      const toastManager = useToastManager()
+      const data = Route.useLoaderData()
+      const { collection } = Route.useParams() as { collection: string }
+      const search = Route.useSearch() as z.infer<typeof searchSchema>
+      const navigate = useNavigate()
+      const collectionDef = getCollectionDefinition(collection) as CollectionDefinition
+      const adminConfig = getCollectionAdminConfig(collection)
+      const columns = adminConfig?.columns || []
+      const workflowStatuses = getWorkflowStatuses(collectionDef)
+
+      // Ref-guarded so the post-create toast fires exactly once per arrival with
+      // ?action=created. Base UI's useToastManager returns a new memoized object
+      // whenever its internal toasts array changes — depending on `toastManager`
+      // (the object) in the deps array would create a loop: add() updates toasts
+      // → new toastManager identity → effect re-fires → add again. We depend on
+      // `toastManager.add` (the underlying store method, which is stable), and
+      // the ref is belt-and-suspenders protection against any re-fire that
+      // observes `search.action === 'created'` before navigate clears it.
+      const createdToastFiredRef = useRef(false)
+      useEffect(() => {
+        if (search.action !== 'created') {
+          createdToastFiredRef.current = false
+          return
+        }
+        if (createdToastFiredRef.current) return
+        createdToastFiredRef.current = true
+
+        toastManager.add({
+          title: `${collectionDef.labels.singular} Created`,
+          description: `Successfully created ${collectionDef.labels.singular.toLowerCase()}`,
+          data: {
+            intent: 'success',
+            iconType: 'success',
+            icon: true,
+            close: true,
+          },
+        })
+        navigate({
+          to: '.',
+          search: (prev: Record<string, unknown>) => ({ ...prev, action: undefined }),
+          replace: true,
+        })
+      }, [
+        search.action,
+        navigate,
+        toastManager.add,
+        collectionDef.labels.singular.toLowerCase,
+        collectionDef.labels.singular,
+      ])
+
+      const CustomListView = adminConfig?.listView
+
+      return (
+        <>
+          <BreadcrumbsClient
+            breadcrumbs={[
+              { label: 'Dashboard', href: `/admin` },
+              {
+                label: data.included.collection.labels.plural,
+                href: `/admin/collections/${collection}`,
+              },
+            ]}
+          />
+          {CustomListView ? (
+            <CustomListView data={data} workflowStatuses={workflowStatuses} />
+          ) : (
+            <ListView
+              data={data}
+              columns={columns}
+              workflowStatuses={workflowStatuses}
+              useAsTitle={collectionDef.useAsTitle}
+            />
+          )}
+        </>
+      )
+    },
+  })
+
+  return Route
+}

package/src/routes/create-sign-in-route.tsx

@@ -0,0 +1,39 @@
+/**
+ * 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
+ */
+
+/**
+ * Sign-in page route factory.
+ *
+ * Lives outside the `/admin` subtree so the authenticated-admin layout
+ * (and its `beforeLoad` guard) does not apply. Preserves a `callbackUrl`
+ * query param so sign-ins triggered by the admin guard redirect back to
+ * the originally-requested path.
+ */
+
+import { createFileRoute } from '@tanstack/react-router'
+
+import { SignInPage } from '../admin-shell/chrome/sign-in-page.js'
+
+interface SignInSearch {
+  callbackUrl?: string
+}
+
+export function createSignInRoute(path: string) {
+  // biome-ignore lint/suspicious/noExplicitAny: dynamic path bypasses route-tree typing
+  const Route: any = createFileRoute(path as never)({
+    validateSearch: (search: Record<string, unknown>): SignInSearch => {
+      const callbackUrl = typeof search.callbackUrl === 'string' ? search.callbackUrl : undefined
+      return { callbackUrl }
+    },
+    component: function SignInRouteComponent() {
+      const { callbackUrl } = Route.useSearch() as SignInSearch
+      return <SignInPage callbackUrl={callbackUrl} />
+    },
+  })
+  return Route
+}

package/src/routes/index.ts

@@ -0,0 +1,36 @@
+/**
+ * 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
+ */
+
+/**
+ * Route factories for the Byline admin UI on TanStack Start.
+ *
+ * Each factory takes a path string (the host's filesystem-backed route
+ * path) and returns the `Route` object produced by
+ * `createFileRoute(path)({...})`. The host's route file collapses to:
+ *
+ *   import { createCollectionListRoute } from '@byline/host-tanstack-start/routes'
+ *   export const Route = createCollectionListRoute('/(byline)/admin/collections/$collection/')
+ *
+ * Routes that need host-specific data (i18n bridge component, content
+ * locales) take a second `opts` argument.
+ */
+
+export { createAdminAccountRoute } from './create-admin-account-route.js'
+export { createAdminDashboardRoute } from './create-admin-dashboard-route.js'
+export { createAdminLayoutRoute } from './create-admin-layout-route.js'
+export { createAdminPermissionsRoute } from './create-admin-permissions-route.js'
+export { createAdminRoleEditRoute } from './create-admin-role-edit-route.js'
+export { createAdminRolesListRoute } from './create-admin-roles-list-route.js'
+export { createAdminUserEditRoute } from './create-admin-user-edit-route.js'
+export { createAdminUsersListRoute } from './create-admin-users-list-route.js'
+export { createCollectionApiRoute } from './create-collection-api-route.js'
+export { createCollectionCreateRoute } from './create-collection-create-route.js'
+export { createCollectionEditRoute } from './create-collection-edit-route.js'
+export { createCollectionHistoryRoute } from './create-collection-history-route.js'
+export { createCollectionListRoute } from './create-collection-list-route.js'
+export { createSignInRoute } from './create-sign-in-route.js'

package/src/server-fns/admin-account/change-password.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 { createServerFn } from '@tanstack/react-start'
+
+import { type AccountResponse, changeAccountPasswordCommand } from '@byline/admin/admin-account'
+
+import { getAdminRequestContext } from '../../auth/auth-context.js'
+import { bylineCore } from '../../integrations/byline-core.js'
+
+export interface ChangeAccountPasswordInput {
+  vid: number
+  currentPassword: string
+  newPassword: string
+}
+
+export const changeAccountPassword = createServerFn({ method: 'POST' })
+  .inputValidator((input: ChangeAccountPasswordInput) => input)
+  .handler(async ({ data }): Promise<AccountResponse> => {
+    const context = await getAdminRequestContext()
+    return changeAccountPasswordCommand(context, data, { store: bylineCore().adminStore! })
+  })