@modern-admin/react 0.1.0

package/src/i18n.tsx

@@ -0,0 +1,267 @@
+// React bindings for @modern-admin/i18n. Wraps the I18n registry in a
+// provider, persists the active locale in localStorage, and exposes a
+// `useI18n()` hook that re-renders subscribers on locale changes.
+
+import * as React from 'react'
+import { I18n, builtinLocales, type LocaleBundle } from '@modern-admin/i18n'
+import type { KeyValueFieldSpec, PropertyJSON, RelatedResource, ResourceJSON } from './types.js'
+
+const STORAGE_KEY = 'modern-admin:locale'
+
+export interface MetadataKeyValueFieldTranslations {
+  label?: string
+  description?: string
+  placeholder?: string
+  availableValues?: Record<string, string>
+}
+
+export interface MetadataPropertyTranslations {
+  label?: string
+  description?: string
+  availableValues?: Record<string, string>
+  keyValueFields?: Record<string, MetadataKeyValueFieldTranslations>
+}
+
+export interface MetadataActionTranslations {
+  /** Display label shown in action menus, buttons, and tooltips. */
+  label?: string
+}
+
+export interface MetadataResourceTranslations {
+  label?: string
+  name?: string
+  navigation?: {
+    name?: string
+    group?: string
+  }
+  properties?: Record<string, MetadataPropertyTranslations>
+  /** Per-action overrides keyed by action name (e.g. `publish`, `archive`). */
+  actions?: Record<string, MetadataActionTranslations>
+  /**
+   * Tab label overrides for related-resource tabs on the show page.
+   * Key is the related resource's `resourceId`.
+   */
+  relatedResources?: Record<string, string>
+}
+
+export interface MetadataLocaleTranslations {
+  navigation?: {
+    groups?: Record<string, string>
+  }
+  resources?: Record<string, MetadataResourceTranslations>
+  properties?: Record<string, MetadataPropertyTranslations>
+}
+
+export type MetadataTranslations = Record<string, MetadataLocaleTranslations>
+
+const isDefined = <T,>(value: T | undefined): value is T => value !== undefined
+
+const firstDefined = <T,>(...values: Array<T | undefined>): T | undefined =>
+  values.find(isDefined)
+
+const localizeAvailableValues = (
+  availableValues: Array<{ value: string; label: string }> | null,
+  ...maps: Array<Record<string, string> | undefined>
+): Array<{ value: string; label: string }> | null => {
+  if (!availableValues) return availableValues
+  return availableValues.map((option) => ({
+    ...option,
+    label: firstDefined(...maps.map((map) => map?.[option.value]), option.label) ?? option.label,
+  }))
+}
+
+const localizeKeyValueField = (
+  field: KeyValueFieldSpec,
+  ...translations: Array<MetadataKeyValueFieldTranslations | undefined>
+): KeyValueFieldSpec => ({
+  ...field,
+  label: firstDefined(...translations.map((translation) => translation?.label), field.label),
+  description: firstDefined(...translations.map((translation) => translation?.description), field.description),
+  placeholder: firstDefined(...translations.map((translation) => translation?.placeholder), field.placeholder),
+  availableValues: field.availableValues?.map((option) => {
+    if (typeof option === 'string') {
+      const label =
+        firstDefined(...translations.map((translation) => translation?.availableValues?.[option]), option) ??
+        option
+      return { value: option, label }
+    }
+    return {
+      ...option,
+      label:
+        firstDefined(...translations.map((translation) => translation?.availableValues?.[option.value]), option.label) ??
+        option.label,
+    }
+  }),
+})
+
+/**
+ * Applies translated tab labels to `relatedResources`. Each translation map
+ * is keyed by `resourceId`; the first map that has a matching entry wins.
+ * Exported for unit testing.
+ */
+export const localizeRelatedResources = (
+  relatedResources: RelatedResource[] | undefined,
+  ...translations: Array<Record<string, string> | undefined>
+): RelatedResource[] | undefined => {
+  if (!relatedResources) return relatedResources
+  return relatedResources.map((r) => {
+    const translatedLabel = firstDefined(...translations.map((map) => map?.[r.resourceId]))
+    return translatedLabel !== undefined ? { ...r, label: translatedLabel } : r
+  })
+}
+
+const localizeProperty = (
+  property: PropertyJSON,
+  ...translations: Array<MetadataPropertyTranslations | undefined>
+): PropertyJSON => ({
+  ...property,
+  label: firstDefined(...translations.map((translation) => translation?.label), property.label) ?? property.label,
+  description: firstDefined(...translations.map((translation) => translation?.description), property.description),
+  availableValues: localizeAvailableValues(
+    property.availableValues,
+    ...translations.map((translation) => translation?.availableValues),
+  ),
+  keyValueFields: property.keyValueFields?.map((field) =>
+    localizeKeyValueField(
+      field,
+      ...translations.map((translation) => translation?.keyValueFields?.[field.key]),
+    ),
+  ),
+})
+
+interface I18nContextValue {
+  locale: string
+  setLocale(code: string): void
+  t(key: string, params?: Record<string, unknown>): string
+  availableLocales(): Array<{ code: string; name: string }>
+  localizeResource(resource: ResourceJSON): ResourceJSON
+}
+
+const I18nContext = React.createContext<I18nContextValue | null>(null)
+
+export interface I18nProviderProps {
+  children: React.ReactNode
+  /** Override or extend the bundled locales. Defaults to all 9 built-ins. */
+  locales?: LocaleBundle[]
+  defaultLocale?: string
+  fallbackLocale?: string
+  metadataTranslations?: MetadataTranslations
+}
+
+export function I18nProvider({
+  children,
+  locales = builtinLocales,
+  defaultLocale,
+  fallbackLocale = 'en',
+  metadataTranslations,
+}: I18nProviderProps): React.ReactElement {
+  const i18n = React.useMemo(() => {
+    const initial =
+      (typeof localStorage !== 'undefined' && localStorage.getItem(STORAGE_KEY)) ||
+      defaultLocale ||
+      locales[0]?.code
+    return new I18n({ locales, defaultLocale: initial ?? undefined, fallbackLocale })
+  }, [locales, defaultLocale, fallbackLocale])
+
+  const [locale, setLocaleState] = React.useState(() => i18n.locale)
+
+  const localizeResource = React.useCallback(
+    (resource: ResourceJSON): ResourceJSON => {
+      const localeMeta = metadataTranslations?.[locale]
+      const fallbackMeta = metadataTranslations?.[fallbackLocale]
+      const resourceLocale = localeMeta?.resources?.[resource.id]
+      const resourceFallback = fallbackMeta?.resources?.[resource.id]
+      const localizedName =
+        firstDefined(resourceLocale?.label, resourceLocale?.name, resourceFallback?.label, resourceFallback?.name, resource.name) ??
+        resource.name
+      const group = resource.navigation?.group
+      return {
+        ...resource,
+        name: localizedName,
+        navigation:
+          resource.navigation === null
+            ? null
+            : resource.navigation
+              ? {
+                ...resource.navigation,
+                name: firstDefined(
+                  resourceLocale?.navigation?.name,
+                  resourceFallback?.navigation?.name,
+                  resource.navigation.name,
+                ),
+                group: firstDefined(
+                  resourceLocale?.navigation?.group,
+                  resourceFallback?.navigation?.group,
+                  group ? localeMeta?.navigation?.groups?.[group] : undefined,
+                  group ? fallbackMeta?.navigation?.groups?.[group] : undefined,
+                  resource.navigation.group,
+                ),
+              }
+              : resource.navigation,
+        properties: resource.properties.map((property) =>
+          localizeProperty(
+            property,
+            resourceLocale?.properties?.[property.path],
+            localeMeta?.properties?.[property.path],
+            resourceFallback?.properties?.[property.path],
+            fallbackMeta?.properties?.[property.path],
+          ),
+        ),
+        actions: resource.actions.map((action) => {
+          const localizedLabel = firstDefined(
+            resourceLocale?.actions?.[action.name]?.label,
+            resourceFallback?.actions?.[action.name]?.label,
+          )
+          if (localizedLabel === undefined) return action
+          return {
+            ...action,
+            custom: { ...(action.custom ?? {}), label: localizedLabel },
+          }
+        }),
+        relatedResources: localizeRelatedResources(
+          resource.relatedResources,
+          resourceLocale?.relatedResources,
+          resourceFallback?.relatedResources,
+        ),
+      }
+    },
+    [fallbackLocale, locale, metadataTranslations],
+  )
+
+  const setLocale = React.useCallback(
+    (code: string) => {
+      i18n.setLocale(code)
+      if (typeof localStorage !== 'undefined') localStorage.setItem(STORAGE_KEY, code)
+      setLocaleState(i18n.locale)
+    },
+    [i18n],
+  )
+
+  const value = React.useMemo<I18nContextValue>(
+    () => ({
+      locale,
+      setLocale,
+      t: (key, params) => i18n.t(key, params),
+      availableLocales: () => i18n.availableLocales(),
+      localizeResource,
+    }),
+    [locale, setLocale, i18n, localizeResource],
+  )
+
+  return <I18nContext.Provider value={value}>{children}</I18nContext.Provider>
+}
+
+/** Subscribe to the active locale + translations. Falls back to a no-op
+ * implementation when no provider is mounted, so consumers can render
+ * without forcing apps to install i18n. */
+export function useI18n(): I18nContextValue {
+  const ctx = React.useContext(I18nContext)
+  if (ctx) return ctx
+  return {
+    locale: 'en',
+    setLocale: () => {},
+    t: (k) => k,
+    availableLocales: () => [{ code: 'en', name: 'English' }],
+    localizeResource: (resource) => resource,
+  }
+}

package/src/index.ts

@@ -0,0 +1,192 @@
+// @modern-admin/react — React-side runtime: provider, hooks, property-type
+// renderers, ComponentLoader, and a default <AdminApp> shell.
+
+export {
+  AdminClient,
+  AdminApiError,
+  type AdminClientOptions,
+  type AuthUiProps,
+  type AiAssistantChatEnqueueResponse,
+  type AiAssistantChatMessage,
+  type AiAssistantChatResponse,
+  type AiAssistantCitation,
+  type AiAssistantSettings,
+  type AiAssistantTask,
+  type ApiKeyRecord,
+  type UploadedFileInfo,
+  type UploadProgress,
+  type UploadFileOptions,
+  type UploadFilesOptions,
+} from './client.js'
+export { ComponentLoader, type ComponentEntry } from './component-loader.js'
+export {
+  registerSidebarItem,
+  registerSettingsSection,
+  registerPropertyExtension,
+  registerExtensionRoute,
+  getSidebarExtensions,
+  getSettingsSectionExtensions,
+  getPropertyExtension,
+  getRouteExtension,
+  _resetExtensionRegistry,
+  type SidebarExtension,
+  type SettingsExtension,
+  type PropertyExtension,
+  type RouteExtension,
+} from './extension-registry.js'
+export {
+  ModernAdminProvider,
+  useAdminClient,
+  useAdminContext,
+  type ModernAdminProviderProps,
+} from './provider.js'
+export {
+  useAdminConfig,
+  useFeatures,
+  useResource,
+  useResources,
+  useRecords,
+  useRecord,
+  useCreateRecord,
+  useUpdateRecord,
+  useDeleteRecord,
+  useBulkDeleteRecords,
+  useInvokeResourceAction,
+  useSearchRecords,
+  useCurrentUser,
+  useLogin,
+  useLogout,
+  useAuthUiProps,
+  useSocialLogin,
+  type CurrentUserResult,
+} from './hooks.js'
+export {
+  PropertyDisplay,
+  PropertyEditor,
+  type PropertyDisplayProps,
+  type PropertyEditorProps,
+} from './property-renderer.js'
+export {
+  ReferenceLink,
+  ReferenceLinkList,
+  ReferenceCombobox,
+  ReferenceMultiCombobox,
+} from './reference.js'
+export {
+  I18nProvider,
+  useI18n,
+  type I18nProviderProps,
+  type MetadataKeyValueFieldTranslations,
+  type MetadataPropertyTranslations,
+  type MetadataActionTranslations,
+  type MetadataResourceTranslations,
+  type MetadataLocaleTranslations,
+  type MetadataTranslations,
+} from './i18n.js'
+export { useHotkey, type HotkeyOptions } from './use-hotkey.js'
+export {
+  HotkeyRegistryProvider,
+  useRegisteredHotkeys,
+  type HotkeyDescriptor,
+} from './hotkey-registry.js'
+export { HotkeyHelpButton } from './hotkey-help.js'
+export { ThemeToggle, LanguageSwitcher } from './header-controls.js'
+export { NotifyToaster, useNotify, type NotifyMessage } from './notify.js'
+export {
+  DialogsProvider,
+  useDialogs,
+  type DialogsApi,
+  type ConfirmOptions,
+  type AlertOptions,
+  type OpenOptions,
+  type DialogsProviderProps,
+} from './dialogs.js'
+export { confirmGuard } from './action-guard.js'
+export {
+  buildValidationSchema,
+  buildPropertySchema,
+  defaultValueFor,
+  type FormValuesGetter,
+  type Translator,
+} from './validation.js'
+export { evaluateShowWhen } from './show-when.js'
+export {
+  Link,
+  useRoute,
+  useNavigate,
+  useOpenInNewTab,
+  buildHref,
+  parseLocation,
+  type Route,
+  type ListQueryState,
+  type LinkProps,
+} from './router.js'
+export { AdminApp, type AdminAppProps } from './admin-app.js'
+export { LoginPage, type LoginPageProps } from './pages/login-page.js'
+export {
+  useRealtimeInvalidation,
+  applyDeletionLocally,
+  type RealtimeSubscriber,
+  type RealtimeWireEvent,
+} from './realtime.js'
+export { ResourceListPage } from './pages/list-page.js'
+export { ResourceShowPage } from './pages/show-page.js'
+export { ResourceEditPage } from './pages/edit-page.js'
+export {
+  ResourceWizardCreatePage,
+  type ResourceWizardCreatePageProps,
+} from './pages/wizard-create-page.js'
+export {
+  WizardForm,
+  type WizardStep,
+  type WizardFormLabels,
+  type WizardFormProps,
+} from './components/wizard-form.js'
+export { HomePage } from './pages/home-page.js'
+export { ExportDialog, type ExportDialogProps } from './pages/export-dialog.js'
+export {
+  PageBreadcrumbs,
+  homeCrumb,
+  type BreadcrumbItemSpec,
+  type PageBreadcrumbsProps,
+} from './breadcrumbs.js'
+export {
+  fetchAllRecords,
+  recordsToCsv,
+  recordsToJson,
+  csvEscape,
+  downloadText,
+  exportFilename,
+  type ExportFormat,
+  type FetchAllOptions,
+  type SerializeOptions,
+} from './export.js'
+export type {
+  AdminConfig,
+  AdminFeatures,
+  ActionDescriptor,
+  CurrentUser,
+  ListQuery,
+  ListResponse,
+  PropertyJSON,
+  RecordJSON,
+  RecordResponse,
+  RelatedResource,
+  ResourceJSON,
+  ShowWhenSpec,
+  View,
+} from './types.js'
+export { RelatedRecordsTabs } from './components/related-records-tabs.js'
+export {
+  ReferenceMultiTableDialog,
+  type ReferenceMultiTableDialogProps,
+} from './components/reference-multi-table-dialog.js'
+export {
+  LocalStorageDashboardStore,
+  ServerDashboardStore,
+  useDashboardCharts,
+  resolveRange,
+  emitDashboardReload,
+  type UseDashboardChartsOptions,
+  type UseDashboardChartsResult,
+} from './use-dashboard-charts.js'

package/src/notify.tsx

@@ -0,0 +1,94 @@
+// Global, i18n-aware toast notifications.
+//
+// `useNotify()` returns a typed surface that translates message keys before
+// handing them to sonner. Mount `<NotifyToaster />` once at the app root —
+// it wraps the shadcn-flavoured `<Toaster />` with sensible defaults.
+// Helpers also accept raw strings (already-translated) for cases where the
+// caller has the literal text on hand (server error messages, etc.).
+
+import * as React from 'react'
+import { Toaster, toast, type ToasterProps } from '@modern-admin/ui'
+import { useI18n } from './i18n.js'
+
+export interface NotifyMessage {
+  /** i18n key, e.g. 'toast:saved' */
+  key?: string
+  /** Already-translated literal text (used as-is when present). */
+  message?: string
+  /** Interpolation params for the `key` lookup. */
+  params?: Record<string, unknown>
+  /** Optional secondary line. */
+  description?: string
+}
+
+type Input = string | NotifyMessage
+
+interface NotifyApi {
+  success(input: Input, opts?: { description?: string }): void
+  error(input: Input, opts?: { description?: string }): void
+  info(input: Input, opts?: { description?: string }): void
+  warning(input: Input, opts?: { description?: string }): void
+  /** Show loading -> success/error around a promise. Strings are i18n keys. */
+  promise<T>(
+    p: Promise<T>,
+    messages: { loading: Input; success: Input | ((value: T) => Input); error: Input | ((err: unknown) => Input) },
+  ): Promise<T>
+  /** Escape hatch for callers that want raw sonner access. */
+  raw: typeof toast
+}
+
+/** The global toaster. Mount once near the root of the admin shell. */
+export function NotifyToaster(props: ToasterProps): React.ReactElement {
+  return <Toaster richColors closeButton position="top-right" {...props} />
+}
+
+/** Hook returning a translation-aware notification surface. */
+export function useNotify(): NotifyApi {
+  const { t } = useI18n()
+
+  const resolve = React.useCallback(
+    (input: Input): { title: string; description?: string } => {
+      if (typeof input === 'string') return { title: input }
+      const title = input.key ? t(input.key, input.params) : (input.message ?? '')
+      return input.description ? { title, description: input.description } : { title }
+    },
+    [t],
+  )
+
+  return React.useMemo<NotifyApi>(
+    () => ({
+      success: (input, opts) => {
+        const r = resolve(input)
+        toast.success(r.title, { description: opts?.description ?? r.description })
+      },
+      error: (input, opts) => {
+        const r = resolve(input)
+        toast.error(r.title, { description: opts?.description ?? r.description })
+      },
+      info: (input, opts) => {
+        const r = resolve(input)
+        toast.info(r.title, { description: opts?.description ?? r.description })
+      },
+      warning: (input, opts) => {
+        const r = resolve(input)
+        toast.warning(r.title, { description: opts?.description ?? r.description })
+      },
+      promise: (p, messages) => {
+        toast.promise(p, {
+          loading: resolve(messages.loading).title,
+          success: (value) => {
+            const m = typeof messages.success === 'function' ? messages.success(value) : messages.success
+            return resolve(m).title
+          },
+          error: (err) => {
+            const m = typeof messages.error === 'function' ? messages.error(err) : messages.error
+            return resolve(m).title
+          },
+        })
+        return p
+      },
+      raw: toast,
+    }),
+    [resolve],
+  )
+}