@modern-admin/react 0.1.0

package/src/router.tsx

@@ -0,0 +1,211 @@
+// Routing engine compat layer over @tanstack/react-router with `createBrowserHistory()`.
+//
+// Why browser history? Clean, standard path-based URLs (`/resources/:id?page=2`).
+// Works with server-side analytics and deep links. Requires an SPA fallback rule
+// on the server (`try_files ... index.html` in nginx, `historyApiFallback` in
+// Vite preview). This is the one-line standard config for any modern static host
+// (Vercel, Netlify, nginx). No SSR is used — admin pages are auth-walled.
+//
+// Why TSR? Future-proof primitives — devtools, search-param schemas, per-route
+// loaders, code-splitting — without paying for SSR/Nitro (TanStack Start).
+//
+// Public API (Route discriminated union, `Link`, `useRoute`, `useNavigate`,
+// `buildHref`) is kept stable. `Route` is the canonical surface; the underlying
+// TSR state is mapped to it via `parseLocation`. Search params are kept
+// opaque to TSR (`parseSearch`/`stringifySearch` are no-ops in `admin-router`):
+// `ListQueryState` (with `filters[<key>]=<v>` keys) is parsed manually from
+// the raw `searchStr` so the URL format doesn't depend on TSR's JSON-search encoding.
+
+import * as React from 'react'
+import { useRouter, useRouterState } from '@tanstack/react-router'
+
+/**
+ * Provides the SPA mount basepath (e.g. `/admin`) to all navigation
+ * primitives (`Link`, `useNavigate`, `useRoute`). Set by
+ * `AdminRouterProvider` from `window.__MODERN_ADMIN__.basePath`. Defaults
+ * to `''` (root mount).
+ */
+export const BasepathContext = React.createContext<string>('')
+
+/** Returns the normalised basepath (never has a trailing slash; `''` at root). */
+export const useBasepath = (): string => React.useContext(BasepathContext)
+
+/** URL-persisted state for the resource list page. */
+export interface ListQueryState {
+  page?: number
+  perPage?: number
+  sortBy?: string
+  direction?: 'asc' | 'desc'
+  /** Per-column filter values keyed by property path. */
+  filters?: Record<string, string>
+}
+
+export type Route =
+  | { name: 'home' }
+  | { name: 'audit-log' }
+  | { name: 'list'; resourceId: string; query?: ListQueryState }
+  | { name: 'show'; resourceId: string; recordId: string }
+  | { name: 'edit'; resourceId: string; recordId: string }
+  | { name: 'new'; resourceId: string }
+  /** Settings hub. Sub-section selected via `section` (e.g. 'api-keys'). */
+  | { name: 'settings'; section?: string }
+  /**
+   * Extension page registered by a Pro plugin via `registerExtensionRoute`.
+   * Renders at `/ext/<key>` inside the authenticated admin shell.
+   */
+  | { name: 'extension'; key: string }
+
+const parseListQuery = (search: string): ListQueryState | undefined => {
+  if (!search) return undefined
+  const params = new URLSearchParams(search.startsWith('?') ? search.slice(1) : search)
+  const out: ListQueryState = {}
+  const page = params.get('page')
+  if (page) {
+    const n = Number(page)
+    if (Number.isFinite(n) && n >= 1) out.page = n
+  }
+  const perPage = params.get('perPage')
+  if (perPage) {
+    const n = Number(perPage)
+    if (Number.isFinite(n) && n >= 1) out.perPage = n
+  }
+  const sortBy = params.get('sortBy')
+  if (sortBy) out.sortBy = sortBy
+  const direction = params.get('direction')
+  if (direction === 'asc' || direction === 'desc') out.direction = direction
+  const filters: Record<string, string> = {}
+  params.forEach((value, key) => {
+    const m = key.match(/^filters\[(.+)\]$/)
+    if (m && m[1] != null && value !== '') filters[m[1]] = value
+  })
+  if (Object.keys(filters).length > 0) out.filters = filters
+  return Object.keys(out).length > 0 ? out : undefined
+}
+
+const buildListQuery = (q: ListQueryState | undefined): string => {
+  if (!q) return ''
+  const params = new URLSearchParams()
+  if (q.page != null && q.page !== 1) params.set('page', String(q.page))
+  if (q.perPage != null && q.perPage !== 20) params.set('perPage', String(q.perPage))
+  if (q.sortBy) params.set('sortBy', q.sortBy)
+  if (q.direction) params.set('direction', q.direction)
+  if (q.filters) {
+    for (const [k, v] of Object.entries(q.filters)) {
+      if (v != null && v !== '') params.set(`filters[${k}]`, v)
+    }
+  }
+  const s = params.toString()
+  return s ? `?${s}` : ''
+}
+
+/** Map a TSR location (pathname + raw searchStr) to the canonical `Route`
+ *  union the rest of the codebase consumes. Pure — used both at render
+ *  time (via `useRoute`) and outside the React tree if ever needed. */
+export const parseLocation = (pathname: string, searchStr: string): Route => {
+  const parts = pathname.split('/').filter(Boolean)
+  if (parts.length === 0) return { name: 'home' }
+  if (parts[0] === 'audit-log') return { name: 'audit-log' }
+  if (parts[0] === 'settings') {
+    const section = parts[1] ? decodeURIComponent(parts[1]) : undefined
+    return section ? { name: 'settings', section } : { name: 'settings' }
+  }
+  if (parts[0] === 'ext' && parts[1]) {
+    return { name: 'extension', key: decodeURIComponent(parts[1]) }
+  }
+  if (parts[0] === 'resources' && parts[1]) {
+    const resourceId = decodeURIComponent(parts[1])
+    if (parts[2] === 'new') return { name: 'new', resourceId }
+    if (parts[2] && parts[3] === 'edit') {
+      return { name: 'edit', resourceId, recordId: decodeURIComponent(parts[2]) }
+    }
+    if (parts[2]) return { name: 'show', resourceId, recordId: decodeURIComponent(parts[2]) }
+    const query = parseListQuery(searchStr)
+    return query ? { name: 'list', resourceId, query } : { name: 'list', resourceId }
+  }
+  return { name: 'home' }
+}
+
+/** Build a path URL for the given route. Pure — kept for tests and for
+ *  `<Link>` href generation. */
+export const buildHref = (route: Route): string => {
+  switch (route.name) {
+  case 'home':
+    return '/'
+  case 'audit-log':
+    return '/audit-log'
+  case 'list':
+    return `/resources/${encodeURIComponent(route.resourceId)}${buildListQuery(route.query)}`
+  case 'show':
+    return `/resources/${encodeURIComponent(route.resourceId)}/${encodeURIComponent(route.recordId)}`
+  case 'edit':
+    return `/resources/${encodeURIComponent(route.resourceId)}/${encodeURIComponent(route.recordId)}/edit`
+  case 'new':
+    return `/resources/${encodeURIComponent(route.resourceId)}/new`
+  case 'settings':
+    return route.section ? `/settings/${encodeURIComponent(route.section)}` : '/settings'
+  case 'extension':
+    return `/ext/${encodeURIComponent(route.key)}`
+  }
+}
+
+/** Current canonical route, derived from the live TSR state.
+ *  When the router has a basepath, TSR strips it from `location.pathname`
+ *  before exposing it in state — so `parseLocation` sees only the
+ *  basepath-relative portion. */
+export const useRoute = (): Route =>
+  useRouterState({
+    select: (s) => parseLocation(s.location.pathname, s.location.searchStr ?? ''),
+  })
+
+/** Imperative navigator. Same signature as the legacy custom router so
+ *  call-sites don't change. Goes through TSR history → re-routing flows
+ *  through TSR's lifecycle. */
+export const useNavigate = (): ((route: Route) => void) => {
+  const router = useRouter()
+  const basepath = useBasepath()
+  return React.useCallback(
+    (next: Route) => {
+      router.history.push(basepath + buildHref(next))
+    },
+    [router, basepath],
+  )
+}
+
+/** Open an in-app route in a new browser tab, honouring the admin's
+ *  `basepath`. `buildHref` returns a basepath-relative path, so we prepend
+ *  the basepath the same way `Link`/`useNavigate` do — otherwise the new tab
+ *  loads a URL outside the admin mount (e.g. `/resources/...` instead of
+ *  `/admin/resources/...`). */
+export const useOpenInNewTab = (): ((route: Route) => void) => {
+  const basepath = useBasepath()
+  return React.useCallback((route: Route) => {
+    if (typeof window === 'undefined') return
+    window.open(basepath + buildHref(route), '_blank', 'noopener,noreferrer')
+  }, [basepath])
+}
+
+export interface LinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+  to: Route
+}
+
+/** Anchor with path href + client-side navigation on plain left-click.
+ *  Modifier clicks (cmd/ctrl/shift/alt, middle button) fall through to
+ *  default browser behaviour so "open in new tab" keeps working. */
+export const Link = ({ to, onClick, ...rest }: LinkProps): React.ReactElement => {
+  const router = useRouter()
+  const basepath = useBasepath()
+  const href = basepath + buildHref(to)
+  const handleClick = React.useCallback(
+    (event: React.MouseEvent<HTMLAnchorElement>) => {
+      onClick?.(event)
+      if (event.defaultPrevented) return
+      if (event.button !== 0) return
+      if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return
+      if (rest.target && rest.target !== '_self') return
+      event.preventDefault()
+      router.history.push(href)
+    },
+    [onClick, router, href, rest.target],
+  )
+  return <a href={href} onClick={handleClick} {...rest} />
+}

package/src/show-when.ts

@@ -0,0 +1,76 @@
+// Pure helper that evaluates a `ShowWhenSpec` against a snapshot of form
+// values. Lives outside React/RHF on purpose so both the edit page renderer
+// and the validation builder can share the exact same semantics.
+//
+// Operator semantics:
+//   - `equals`            — control value === provided value
+//   - `notEquals`         — control value !== provided value
+//   - `in`                — control value matches any item in array
+//   - `notIn`             — control value matches none of the items
+//   - `isEmpty:true`      — control value is null / undefined / ''
+//   - `isEmpty:false`     — control value is NOT null / undefined / ''
+//   - `defaultWhenEmpty`  — fallback: shows the field when control is empty,
+//                           regardless of the other operators
+//
+// Operators combine with OR — the field shows when **any** of them passes.
+// When no operator is configured, the rule trivially passes (visible).
+
+import type { ShowWhenSpec } from './types.js'
+
+const isBlank = (v: unknown): boolean =>
+  v === undefined || v === null || (typeof v === 'string' && v.trim() === '')
+
+/** Loose equality that handles primitives + dates + arrays of primitives. */
+const sameValue = (a: unknown, b: unknown): boolean => {
+  if (a === b) return true
+  if (a == null || b == null) return false
+  if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime()
+  // Coerce numbers vs string-numbers (HTML inputs ship strings).
+  if (typeof a === 'number' && typeof b === 'string') return String(a) === b
+  if (typeof a === 'string' && typeof b === 'number') return a === String(b)
+  if (typeof a === 'boolean' && typeof b === 'string') return String(a) === b
+  return false
+}
+
+/**
+ * Evaluate a `ShowWhenSpec` against the live form values.
+ * Returns `true` (visible) when no rule is configured.
+ */
+export function evaluateShowWhen(
+  rule: ShowWhenSpec | undefined,
+  values: Record<string, unknown>,
+): boolean {
+  if (!rule) return true
+  const control = values[rule.field]
+  const empty = isBlank(control)
+
+  // Default branch: when control is empty AND defaultWhenEmpty is set, show.
+  if (rule.defaultWhenEmpty && empty) return true
+
+  let anyOperator = false
+
+  if ('equals' in rule && rule.equals !== undefined) {
+    anyOperator = true
+    if (sameValue(control, rule.equals)) return true
+  }
+  if ('notEquals' in rule && rule.notEquals !== undefined) {
+    anyOperator = true
+    if (!sameValue(control, rule.notEquals)) return true
+  }
+  if (rule.in && rule.in.length > 0) {
+    anyOperator = true
+    if (rule.in.some((v) => sameValue(control, v))) return true
+  }
+  if (rule.notIn && rule.notIn.length > 0) {
+    anyOperator = true
+    if (!rule.notIn.some((v) => sameValue(control, v))) return true
+  }
+  if (rule.isEmpty !== undefined) {
+    anyOperator = true
+    if (rule.isEmpty === empty) return true
+  }
+
+  // Rule with operators that all failed → hidden.
+  // Rule with no operators (only `field` declared) → visible.
+  return !anyOperator
+}

package/src/types.ts

@@ -0,0 +1,198 @@
+// Wire-shape mirror of `ResourceDecorator#toJSON()` and friends. We re-declare
+// rather than re-import so the React bundle doesn't drag in the full core
+// (which references Node-only deps in a few corners).
+
+export type View = 'list' | 'show' | 'edit' | 'filter'
+
+/**
+ * Mirror of `core` `ShowWhen` — declarative rule that conditionally hides a
+ * field on the edit form based on the current value of another form field.
+ * Operators combine with OR semantics; `defaultWhenEmpty` triggers when the
+ * control field is null / undefined / ''.
+ */
+export interface ShowWhenSpec {
+  field: string
+  equals?: unknown
+  notEquals?: unknown
+  in?: unknown[]
+  notIn?: unknown[]
+  isEmpty?: boolean
+  defaultWhenEmpty?: boolean
+}
+
+/**
+ * Mirror of `core` `KeyValueField` — declares one row in the key-value
+ * editor used as a friendly alternative to the raw JSON editor.
+ */
+export interface KeyValueFieldSpec {
+  key: string
+  label?: string
+  type?: 'string' | 'number' | 'boolean' | 'textarea' | 'select' | 'autocomplete'
+  description?: string
+  placeholder?: string
+  isRequired?: boolean
+  availableValues?: ReadonlyArray<string | { value: string; label: string }>
+  /** For `type: 'autocomplete'`: pull dynamic suggestions from another resource. */
+  suggestionsResource?: string
+  /** Path of the field on `suggestionsResource` to project. */
+  suggestionsField?: string
+}
+
+export interface PropertyJSON {
+  path: string
+  label: string
+  type: string
+  isId: boolean
+  isSortable: boolean
+  isRequired: boolean
+  isDisabled: boolean
+  isArray: boolean
+  reference: string | null
+  availableValues: Array<{ value: string; label: string }> | null
+  components: { list?: string; edit?: string; show?: string; filter?: string } | Record<string, string>
+  visibility: Record<View, boolean>
+  position: number
+  description?: string
+  showWhen?: ShowWhenSpec
+  keyValueFields?: KeyValueFieldSpec[]
+  custom: Record<string, unknown>
+}
+
+export interface ActionGroup {
+  name: string
+  icon?: string
+}
+
+export interface ActionDescriptor {
+  name: string
+  actionType: 'resource' | 'record' | 'bulk'
+  resourceId: string
+  nesting?: ActionGroup[]
+  guard?: string
+  component?: string | null
+  custom?: Record<string, unknown>
+}
+
+export interface RelatedResource {
+  resourceId: string
+  foreignKey: string
+  label?: string
+}
+
+export interface ResourceJSON {
+  id: string
+  name: string
+  navigation: { name?: string; icon?: string; group?: string } | null
+  relatedResources?: RelatedResource[]
+  properties: PropertyJSON[]
+  actions: ActionDescriptor[]
+}
+
+export interface CurrentUser {
+  id: string
+  email?: string
+  name?: string
+  role?: string
+  avatarUrl?: string
+  [claim: string]: unknown
+}
+
+/**
+ * Mirror of `core` `AdminFeatures`. Each flag is `true` iff the
+ * corresponding backend subsystem is wired and ready. The SPA uses these
+ * to hide UI surfaces (audit-log link, settings sections, revisions
+ * button, AI assistant widget) for features the host hasn't enabled.
+ */
+export interface AdminFeatures {
+  auditLog: boolean
+  history: boolean
+  webhooks: boolean
+  apiKeys: boolean
+  aiAssistant: boolean
+}
+
+const ALL_FEATURES_OFF: AdminFeatures = {
+  auditLog: false,
+  history: false,
+  webhooks: false,
+  apiKeys: false,
+  aiAssistant: false,
+}
+
+/** Defensive resolver for older API servers that don't yet surface
+ *  `features` in their `/admin/api/config` payload — every flag falls back
+ *  to `false`, so optional surfaces stay hidden until the backend opts in. */
+export const resolveFeatures = (raw?: Partial<AdminFeatures>): AdminFeatures => ({
+  ...ALL_FEATURES_OFF,
+  ...(raw ?? {}),
+})
+
+export interface AdminConfig {
+  rootPath: string
+  branding?: { companyName?: string; logo?: string; theme?: string }
+  auth: Record<string, unknown>
+  resources: ResourceJSON[]
+  features?: Partial<AdminFeatures>
+}
+
+export interface RecordJSON {
+  id: string
+  title: string
+  params: Record<string, unknown>
+  populated: Record<string, unknown>
+  errors: Record<string, unknown>
+  baseError: unknown | null
+}
+
+export interface ListResponse {
+  records: RecordJSON[]
+  meta: { total: number; page: number; perPage: number; sortBy?: string; direction?: 'asc' | 'desc' }
+}
+
+export interface RecordResponse {
+  record: RecordJSON
+}
+
+/** Generic response from a custom action invocation (record / bulk / resource). */
+export interface CustomActionResponse {
+  record?: RecordJSON
+  records?: RecordJSON[]
+  notice?: { message: string; type: 'success' | 'info' | 'error' | 'warning' }
+  redirectUrl?: string
+  [key: string]: unknown
+}
+
+export interface ListQuery {
+  page?: number
+  perPage?: number
+  sortBy?: string
+  direction?: 'asc' | 'desc'
+  filters?: Record<string, string>
+}
+
+/**
+ * Props contract for a property **display** component. Shared between the
+ * built-in `PropertyDisplay` and any custom property extension registered
+ * via `registerPropertyExtension`.
+ */
+export interface PropertyDisplayProps {
+  property: PropertyJSON
+  value: unknown
+  view?: 'list' | 'show'
+  /** The record's `populated` map (pre-fetched reference titles). */
+  populated?: Record<string, unknown>
+}
+
+/**
+ * Props contract for a property **editor** component. Shared between the
+ * built-in `PropertyEditor` and any custom property extension registered
+ * via `registerPropertyExtension`.
+ */
+export interface PropertyEditorProps {
+  property: PropertyJSON
+  value: unknown
+  onChange(next: unknown): void
+  disabled?: boolean
+  /** Required for `type: 'file'` properties to route uploads correctly. */
+  resourceId?: string
+}