@peanut-admin/admin 0.1.0-alpha.11

package/admin-core/src/targets/store.ts

@@ -0,0 +1,153 @@
+import { defineStore } from 'pinia'
+
+export interface TypedTarget {
+  target_resource_key: string
+  target_role: string
+  target_id: string
+}
+
+export interface TypedTargetSet {
+  target_resource_key: string
+  target_role: string
+  target_ids: readonly string[]
+}
+
+export interface TargetCandidate extends TypedTarget {
+  label: string
+  owner_label?: string
+  status?: string
+}
+
+export interface OperationTargetScope {
+  moduleKey: string
+  resourceKey: string
+  operation: string
+  targetResourceKey: string
+  targetRole: string
+  cardinality?: TargetCardinality
+}
+
+export type TargetCardinality = 'none' | 'one_required' | 'zero_or_one' | 'many_readable' | 'aggregate_read' | 'policy_publish' | 'bulk_write'
+
+interface TargetEntry {
+  scope: OperationTargetScope
+  candidates: TargetCandidate[]
+  selectedIds: string[]
+}
+
+interface TargetStoreState {
+  entries: Record<string, TargetEntry>
+  generation: number
+}
+
+const scopeKey = (scope: OperationTargetScope): string => JSON.stringify([
+  scope.moduleKey,
+  scope.resourceKey,
+  scope.operation,
+  scope.targetResourceKey,
+  scope.targetRole,
+  scope.cardinality ?? 'many_readable',
+])
+
+const normalizeCandidates = (
+  scope: OperationTargetScope,
+  candidates: readonly TargetCandidate[],
+): TargetCandidate[] => {
+  const ids = new Set<string>()
+  return candidates.map(candidate => {
+    if (candidate.target_resource_key !== scope.targetResourceKey
+      || candidate.target_role !== scope.targetRole
+      || candidate.target_id === ''
+      || ids.has(candidate.target_id)) {
+      throw new Error('TARGET_CANDIDATE_SCOPE_INVALID')
+    }
+    ids.add(candidate.target_id)
+    return { ...candidate }
+  })
+}
+
+export const useOperationTargets = defineStore('peanut-admin-operation-targets', {
+  state: (): TargetStoreState => ({ entries: {}, generation: 0 }),
+  actions: {
+    replace(scope: OperationTargetScope, candidates: readonly TargetCandidate[]): void {
+      const key = scopeKey(scope)
+      const normalized = normalizeCandidates(scope, candidates)
+      const available = new Set(normalized.map(candidate => candidate.target_id))
+      const previous = this.entries[key]?.selectedIds ?? []
+      const retained = previous.filter(id => available.has(id))
+      this.entries[key] = {
+        scope: { ...scope },
+        candidates: normalized,
+        selectedIds: normalized.length === 1 ? [normalized[0]!.target_id] : retained,
+      }
+      this.generation += 1
+    },
+    select(scope: OperationTargetScope, targets: readonly TypedTarget[]): void {
+      const key = scopeKey(scope)
+      const entry = this.entries[key]
+      if (entry === undefined) {
+        throw new Error('TARGET_SCOPE_NOT_LOADED')
+      }
+      const available = new Set(entry.candidates.map(candidate => candidate.target_id))
+      const selected = new Set<string>()
+      for (const target of targets) {
+        if (target.target_resource_key !== scope.targetResourceKey
+          || target.target_role !== scope.targetRole
+          || !available.has(target.target_id)) {
+          throw new Error('TARGET_SELECTION_INVALID')
+        }
+        selected.add(target.target_id)
+      }
+      const cardinality = scope.cardinality ?? 'many_readable'
+      if ((cardinality === 'none' && selected.size > 0)
+        || (cardinality === 'one_required' && selected.size !== 1)
+        || (cardinality === 'zero_or_one' && selected.size > 1)
+        || cardinality === 'bulk_write') {
+        throw new Error('TARGET_SELECTION_CARDINALITY_INVALID')
+      }
+      entry.selectedIds = [...selected]
+      this.generation += 1
+    },
+    selected(scope: OperationTargetScope): TypedTarget[] {
+      const entry = this.entries[scopeKey(scope)]
+      return (entry?.selectedIds ?? []).map(targetId => ({
+        target_resource_key: scope.targetResourceKey,
+        target_role: scope.targetRole,
+        target_id: targetId,
+      }))
+    },
+    selectedSet(scope: OperationTargetScope): TypedTargetSet {
+      return {
+        target_resource_key: scope.targetResourceKey,
+        target_role: scope.targetRole,
+        target_ids: this.selected(scope).map(target => target.target_id),
+      }
+    },
+    selectionForRequest(scope: OperationTargetScope): TypedTargetSet {
+      const selection = this.selectedSet(scope)
+      const cardinality = scope.cardinality ?? 'many_readable'
+      if ((cardinality === 'one_required' && selection.target_ids.length !== 1)
+        || (cardinality === 'zero_or_one' && selection.target_ids.length > 1)
+        || (cardinality === 'none' && selection.target_ids.length !== 0)
+        || cardinality === 'bulk_write') {
+        throw new Error('TARGET_SELECTION_CARDINALITY_INVALID')
+      }
+
+      return selection
+    },
+    clearScope(scope: OperationTargetScope): void {
+      delete this.entries[scopeKey(scope)]
+      this.generation += 1
+    },
+    clearModule(moduleKey: string): void {
+      this.entries = Object.fromEntries(
+        Object.entries(this.entries).filter(([, entry]) => entry.scope.moduleKey !== moduleKey),
+      )
+      this.generation += 1
+    },
+    clearAll(): void {
+      this.entries = {}
+      this.generation += 1
+    },
+  },
+})

package/admin-shell/src/config.ts

@@ -0,0 +1,84 @@
+export interface ShellHostConfigInput {
+  brand: {
+    name: string
+    mark: string
+  }
+  audiences: {
+    tenant: { label: string }
+    platform: { label: string }
+  }
+  commands: {
+    switchTenantLabel: string
+    logoutLabel: string
+  }
+}
+
+export interface ShellHostConfig {
+  readonly brand: Readonly<ShellHostConfigInput['brand']>
+  readonly audiences: Readonly<{
+    tenant: Readonly<ShellHostConfigInput['audiences']['tenant']>
+    platform: Readonly<ShellHostConfigInput['audiences']['platform']>
+  }>
+  readonly commands: Readonly<ShellHostConfigInput['commands']>
+}
+
+const assertObject = (value: unknown, path: string): Record<string, unknown> => {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error(`SHELL_CONFIG_INVALID:${path}`)
+  }
+  return value as Record<string, unknown>
+}
+
+const assertKnownFields = (value: Record<string, unknown>, allowed: readonly string[], path = ''): void => {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) {
+      throw new Error(`SHELL_CONFIG_UNKNOWN_FIELD:${path}${key}`)
+    }
+  }
+}
+
+const displayValue = (value: unknown, path: string, maximum: number): string => {
+  if (typeof value !== 'string') throw new Error(`SHELL_CONFIG_INVALID:${path}`)
+  const normalized = value.trim()
+  if (normalized.length === 0 || normalized.length > maximum) {
+    throw new Error(`SHELL_CONFIG_INVALID:${path}`)
+  }
+  return normalized
+}
+
+export const defineShellHostConfig = (input: ShellHostConfigInput): ShellHostConfig => {
+  const root = assertObject(input, 'root')
+  assertKnownFields(root, ['brand', 'audiences', 'commands'])
+
+  const brandInput = assertObject(root.brand, 'brand')
+  const audiencesInput = assertObject(root.audiences, 'audiences')
+  const tenantInput = assertObject(audiencesInput.tenant, 'audiences.tenant')
+  const platformInput = assertObject(audiencesInput.platform, 'audiences.platform')
+  const commandsInput = assertObject(root.commands, 'commands')
+  assertKnownFields(brandInput, ['name', 'mark'], 'brand.')
+  assertKnownFields(audiencesInput, ['tenant', 'platform'], 'audiences.')
+  assertKnownFields(tenantInput, ['label'], 'audiences.tenant.')
+  assertKnownFields(platformInput, ['label'], 'audiences.platform.')
+  assertKnownFields(commandsInput, ['switchTenantLabel', 'logoutLabel'], 'commands.')
+
+  const brand = Object.freeze({
+    name: displayValue(brandInput.name, 'brand.name', 120),
+    mark: displayValue(brandInput.mark, 'brand.mark', 12),
+  })
+  const tenant = Object.freeze({
+    label: displayValue(tenantInput.label, 'audiences.tenant.label', 80),
+  })
+  const platform = Object.freeze({
+    label: displayValue(platformInput.label, 'audiences.platform.label', 80),
+  })
+  const commands = Object.freeze({
+    switchTenantLabel: displayValue(commandsInput.switchTenantLabel, 'commands.switchTenantLabel', 80),
+    logoutLabel: displayValue(commandsInput.logoutLabel, 'commands.logoutLabel', 80),
+  })
+
+  return Object.freeze({
+    brand,
+    audiences: Object.freeze({ tenant, platform }),
+    commands,
+  })
+}

package/admin-shell/src/deployment-mode.ts

@@ -0,0 +1,36 @@
+export type DeploymentMode = 'standalone' | 'multi-tenant'
+
+/**
+ * Minimal router contract shared by host applications without coupling to a
+ * particular Vue Router major version.
+ */
+export interface DeploymentRoute {
+  meta?: {
+    controlPlane?: unknown
+    instanceTool?: boolean
+    [key: string]: unknown
+  }
+  children?: DeploymentRoute[]
+}
+
+export const deploymentMode = (value: unknown): DeploymentMode => (
+  value === 'multi-tenant' ? 'multi-tenant' : 'standalone'
+)
+
+export const allowsInstanceTools = (value: unknown): boolean => value === 'standalone'
+
+export const routesForDeployment = <T extends DeploymentRoute>(
+  routes: T[],
+  mode: DeploymentMode,
+  instanceToolsAllowed = mode === 'standalone',
+): T[] => routes.reduce<T[]>((visible, route) => {
+  if (mode !== 'multi-tenant' && route.meta?.controlPlane !== undefined) return visible
+  if (!instanceToolsAllowed && route.meta?.instanceTool === true) return visible
+  visible.push({
+    ...route,
+    children: route.children
+      ? routesForDeployment(route.children, mode, instanceToolsAllowed)
+      : route.children,
+  } as T)
+  return visible
+}, [])

package/admin-shell/src/index.ts

@@ -0,0 +1,44 @@
+export const ADMIN_SHELL_PACKAGE = '@peanut-admin/admin/shell' as const
+export const ADMIN_SHELL_VERSION = '0.1.0' as const
+
+export { defineShellHostConfig } from './config'
+export type { ShellHostConfig, ShellHostConfigInput } from './config'
+export {
+  AdminShell,
+  PageContent,
+  PageHeader,
+  PageToolbar,
+  PlatformShell,
+  ShellBreadcrumb,
+  ShellHeader,
+  ShellSidebar,
+  ShellTabs,
+} from './layout'
+export type { ShellBreadcrumbItem, ShellIdentity, ShellNavigationItem } from './layout'
+export {
+  ConflictState,
+  EmptyState,
+  ForbiddenState,
+  ModuleUnavailableState,
+  NotFoundState,
+  RateLimitState,
+  ServiceUnavailableState,
+  SessionExpiredState,
+} from './states'
+export { TargetScopeSummary, TargetSelector } from './targets'
+export type { TargetScopeMode } from './targets'
+export { SHELL_THEME_TOKENS } from './theme'
+export type { ShellSlotName, ShellThemeToken } from './theme'
+export { allowsInstanceTools, deploymentMode, routesForDeployment } from './deployment-mode'
+export type { DeploymentMode, DeploymentRoute } from './deployment-mode'
+export { tabFromRoute } from './tabs'
+export type { ShellTab, ShellTabRoute, ShellTabState } from './tabs'
+export {
+  ADMIN_SHELL_OVERRIDE_SLOTS,
+  resolveWorkspaceShell,
+  WORKSPACE_SHELL_OVERRIDE_KEY,
+} from './overrides'
+export type {
+  AdminShellOverrideRegistry,
+  WorkspaceShellResolver,
+} from './overrides'

package/admin-shell/src/layout.ts

@@ -0,0 +1,332 @@
+/* eslint-disable vue/one-component-per-file */
+
+import { ElButton, ElDrawer } from 'element-plus'
+import { defineComponent, h, onBeforeUnmount, onMounted } from 'vue'
+import type { Component, PropType, VNodeChild } from 'vue'
+
+import type { ShellHostConfig } from './config'
+
+export interface ShellIdentity {
+  accountLabel: string
+  contextLabel: string
+  actorLabel: string
+}
+
+export interface ShellNavigationItem {
+  key: string
+  label: string
+  path: string | null
+  children: readonly ShellNavigationItem[]
+}
+
+export interface ShellBreadcrumbItem {
+  label: string
+  path: string | null
+}
+
+const shellProps = {
+  config: { type: Object as PropType<ShellHostConfig>, default: null },
+  identity: { type: Object as PropType<ShellIdentity>, default: null },
+  navigation: { type: Array as PropType<readonly ShellNavigationItem[]>, default: () => [] },
+  breadcrumbs: { type: Array as PropType<readonly ShellBreadcrumbItem[]>, default: () => [] },
+  activePath: { type: String, default: '' },
+  collapsed: { type: Boolean, default: false },
+  mobileOpen: { type: Boolean, default: false },
+  openNavigationLabel: { type: String, default: 'Open navigation' },
+  collapseNavigationLabel: { type: String, default: 'Collapse navigation' },
+  expandNavigationLabel: { type: String, default: 'Expand navigation' },
+  primaryNavigationLabel: { type: String, default: 'Primary navigation' },
+  mobileNavigationLabel: { type: String, default: 'Mobile navigation' },
+  breadcrumbLabel: { type: String, default: 'Breadcrumb' },
+  identityLabel: { type: String, default: 'Current identity' },
+}
+
+const shellEmits = {
+  navigate: (path: string) => typeof path === 'string',
+  'update:collapsed': (collapsed: boolean) => typeof collapsed === 'boolean',
+  'update:mobileOpen': (open: boolean) => typeof open === 'boolean',
+  'switch-tenant': () => true,
+  logout: () => true,
+}
+
+const shellRouteOrigin = 'https://shell.invalid'
+
+const trustedLocalPath = (path: string | null): path is string => {
+  if (path === null
+    || !path.startsWith('/')
+    || path.startsWith('//')
+    || /[\\\u0000-\u001f\u007f]/.test(path)) return false
+
+  try {
+    return new URL(path, shellRouteOrigin).origin === shellRouteOrigin
+  } catch {
+    return false
+  }
+}
+
+const ShellFrame = defineComponent({
+  name: 'ShellFrame',
+  inheritAttrs: false,
+  props: {
+    audience: {
+      type: String as () => 'tenant' | 'platform',
+      required: true,
+    },
+  },
+  setup(props, { attrs, slots }) {
+    return () => h('div', {
+      ...attrs,
+      class: ['pa-shell', `pa-shell--${props.audience}`, attrs.class],
+      'data-audience': props.audience,
+    }, [
+      slots.header?.(),
+      h('div', { class: 'pa-shell__workspace' }, [
+        slots.sidebar?.(),
+        h('div', { class: 'pa-shell__main' }, [
+          slots.breadcrumb?.(),
+          slots.tabs?.(),
+          slots.default?.(),
+        ]),
+      ]),
+    ])
+  },
+})
+
+const WorkspaceShell = defineComponent({
+  name: 'WorkspaceShell',
+  inheritAttrs: false,
+  props: {
+    ...shellProps,
+    audience: {
+      type: String as PropType<'tenant' | 'platform'>,
+      required: true,
+    },
+  },
+  emits: shellEmits,
+  setup(props, { attrs, emit, slots }) {
+    const closeMobile = () => emit('update:mobileOpen', false)
+    const onKeydown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape' && props.mobileOpen) closeMobile()
+    }
+    onMounted(() => document.addEventListener('keydown', onKeydown))
+    onBeforeUnmount(() => document.removeEventListener('keydown', onKeydown))
+
+    const renderNavigation = (items: readonly ShellNavigationItem[], mobile: boolean): VNodeChild[] => items.flatMap(item => {
+      const children = renderNavigation(item.children, mobile)
+      if (!trustedLocalPath(item.path)) {
+        return [h('p', { class: ['pa-shell-navigation__group', 'navigation-group'], key: item.key }, item.label), ...children]
+      }
+      return [h('a', {
+        key: item.key,
+        href: item.path,
+        class: ['pa-shell-navigation__link', 'navigation-link', { 'is-active': props.activePath === item.path }],
+        'aria-current': props.activePath === item.path ? 'page' : undefined,
+        'aria-label': item.label,
+        onClick: (event: MouseEvent) => {
+          event.preventDefault()
+          emit('navigate', item.path as string)
+          if (mobile) closeMobile()
+        },
+      }, [
+        h('span', { class: 'navigation-marker', 'aria-hidden': 'true' }),
+        h('span', item.label),
+      ]), ...children]
+    })
+
+    return () => {
+      if (props.config === null) {
+        return h(ShellFrame, { ...attrs, audience: props.audience }, slots)
+      }
+
+      const audienceLabel = props.config.audiences[props.audience].label
+      const identity = props.identity
+      const commands = [
+        props.audience === 'tenant'
+          ? h(ElButton as unknown as Component, {
+              text: true,
+              onClick: () => emit('switch-tenant'),
+            }, () => props.config?.commands.switchTenantLabel)
+          : null,
+        h(ElButton as unknown as Component, {
+          text: true,
+          onClick: () => emit('logout'),
+        }, () => props.config?.commands.logoutLabel),
+      ]
+      const navigation = h('nav', {
+        class: ['pa-shell-navigation', 'workspace-navigation'],
+        'aria-label': props.primaryNavigationLabel,
+      }, renderNavigation(props.navigation, false))
+      const mobileNavigation = h('div', { class: 'pa-shell-mobile-content' }, [
+        identity === null ? null : h('div', { class: 'pa-shell-mobile-identity', 'aria-label': props.identityLabel }, [
+          h('strong', identity.actorLabel),
+          h('span', identity.contextLabel),
+          h('small', identity.accountLabel),
+        ]),
+        h('nav', {
+          class: ['pa-shell-navigation', 'workspace-navigation'],
+          'aria-label': props.mobileNavigationLabel,
+        }, renderNavigation(props.navigation, true)),
+        h('div', { class: ['pa-shell-mobile-commands', 'mobile-navigation-commands'] }, commands),
+      ])
+
+      return h(ShellFrame, { ...attrs, audience: props.audience }, {
+        header: () => h(ShellHeader, {}, () => [
+          h('button', {
+            type: 'button',
+            class: 'mobile-nav-trigger',
+            'aria-label': props.openNavigationLabel,
+            'aria-expanded': String(props.mobileOpen),
+            onClick: () => emit('update:mobileOpen', true),
+          }, [
+            h('span', { 'aria-hidden': 'true' }),
+            h('span', { 'aria-hidden': 'true' }),
+            h('span', { 'aria-hidden': 'true' }),
+          ]),
+          h('div', { class: ['pa-shell-brand', 'shell-brand'] }, [
+            h('span', { class: ['pa-shell-brand__mark', 'brand-mark'], 'aria-hidden': 'true' }, props.config?.brand.mark),
+            h('span', {}, [h('strong', props.config?.brand.name), h('small', audienceLabel)]),
+          ]),
+          identity === null ? null : h('div', {
+            class: ['pa-shell-identity', 'shell-context'],
+            'aria-label': props.identityLabel,
+          }, [
+            h('span', identity.contextLabel),
+            h('strong', identity.actorLabel),
+            h('small', identity.accountLabel),
+          ]),
+          h('div', { class: ['pa-shell-commands', 'shell-commands'] }, commands),
+        ]),
+        sidebar: () => h(ShellSidebar, { collapsed: props.collapsed }, () => [
+          navigation,
+          h('button', {
+            type: 'button',
+            class: ['pa-shell__collapse', 'sidebar-collapse'],
+            'aria-label': props.collapsed ? props.expandNavigationLabel : props.collapseNavigationLabel,
+            onClick: () => emit('update:collapsed', !props.collapsed),
+          }, props.collapsed ? props.expandNavigationLabel : props.collapseNavigationLabel),
+        ]),
+        breadcrumb: () => h(ShellBreadcrumb, { label: props.breadcrumbLabel }, () => props.breadcrumbs.map((item, index) => (
+          trustedLocalPath(item.path)
+            ? h('a', {
+                key: `${index}:${item.label}`,
+                href: item.path,
+                onClick: (event: MouseEvent) => {
+                  event.preventDefault()
+                  emit('navigate', item.path as string)
+                },
+              }, item.label)
+            : h('span', { key: `${index}:${item.label}`, 'aria-current': 'page' }, item.label)
+        ))),
+        default: () => [
+          slots.default?.(),
+          h(ElDrawer as unknown as Component, {
+            modelValue: props.mobileOpen,
+            'onUpdate:modelValue': (open: boolean) => emit('update:mobileOpen', open),
+            title: props.config?.brand.name,
+            direction: 'ltr',
+            size: 'min(84vw, 320px)',
+            class: 'mobile-navigation-drawer',
+            closeOnPressEscape: true,
+          }, () => mobileNavigation),
+        ],
+      })
+    }
+  },
+})
+
+const createAudienceShell = (name: string, audience: 'tenant' | 'platform') => defineComponent({
+  name,
+  inheritAttrs: false,
+  props: shellProps,
+  emits: shellEmits,
+  setup(props, { attrs, emit, slots }) {
+    return () => h(WorkspaceShell as Component, {
+      ...attrs,
+      ...props,
+      audience,
+      onNavigate: (path: string) => emit('navigate', path),
+      'onUpdate:collapsed': (collapsed: boolean) => emit('update:collapsed', collapsed),
+      'onUpdate:mobileOpen': (open: boolean) => emit('update:mobileOpen', open),
+      onSwitchTenant: () => emit('switch-tenant'),
+      onLogout: () => emit('logout'),
+    } as Record<string, unknown>, slots)
+  },
+})
+
+export const AdminShell = createAudienceShell('AdminShell', 'tenant')
+
+export const PlatformShell = createAudienceShell('PlatformShell', 'platform')
+
+export const ShellHeader = defineComponent({
+  name: 'ShellHeader',
+  setup(_, { slots }) {
+    return () => h('header', { class: 'pa-shell-header' }, slots.default?.())
+  },
+})
+
+export const ShellSidebar = defineComponent({
+  name: 'ShellSidebar',
+  props: {
+    label: { type: String, default: 'Primary navigation' },
+    collapsed: { type: Boolean, default: false },
+  },
+  setup(props, { slots }) {
+    return () => h('aside', {
+      class: ['pa-shell-sidebar', { 'is-collapsed': props.collapsed }],
+      'aria-label': props.label,
+    }, slots.default?.())
+  },
+})
+
+export const ShellBreadcrumb = defineComponent({
+  name: 'ShellBreadcrumb',
+  props: {
+    label: { type: String, default: 'Breadcrumb' },
+  },
+  setup(props, { slots }) {
+    return () => h('nav', { class: 'pa-shell-breadcrumb', 'aria-label': props.label }, slots.default?.())
+  },
+})
+
+export const ShellTabs = defineComponent({
+  name: 'ShellTabs',
+  props: {
+    label: { type: String, default: 'Open pages' },
+  },
+  setup(props, { slots }) {
+    return () => h('nav', { class: 'pa-shell-tabs', 'aria-label': props.label }, slots.default?.())
+  },
+})
+
+export const PageHeader = defineComponent({
+  name: 'PageHeader',
+  setup(_, { slots }) {
+    return () => h('header', { class: 'pa-page-header' }, [
+      h('div', { class: 'pa-page-header__title' }, slots.default?.()),
+      slots.actions === undefined
+        ? null
+        : h('div', { class: 'pa-page-header__actions' }, slots.actions()),
+    ])
+  },
+})
+
+export const PageToolbar = defineComponent({
+  name: 'PageToolbar',
+  props: {
+    label: { type: String, default: 'Page actions' },
+  },
+  setup(props, { slots }) {
+    return () => h('div', {
+      class: 'pa-page-toolbar',
+      role: 'toolbar',
+      'aria-label': props.label,
+    }, slots.default?.())
+  },
+})
+
+export const PageContent = defineComponent({
+  name: 'PageContent',
+  setup(_, { slots }) {
+    return () => h('section', { class: 'pa-page-content' }, slots.default?.())
+  },
+})