feat(modules): company-context module surfaces and schema-driven settings

Adds the read-only company "Active Modules" index page (lists every
instance-activated module with a Settings shortcut) and the schema-driven
settings framework (generic BaseSchemaForm.vue renderer + per-company
persistence in CompanySetting). Bundled because they share the same
routes/api.php edit and the index page's Settings button targets the
settings page.

Backend:

- CompanyModulesController::index() returns every Module::enabled = true row
  with a kebab-case slug (via Str::kebab()) and a has_settings flag computed
  from \InvoiceShelf\Modules\Registry::settingsFor(). nwidart stores module
  names in PascalCase ("HelloWorld") but URLs and registry keys use kebab
  ("hello-world") — the controller normalizes so module authors can call
  Registry::registerSettings('hello-world') naturally without thinking
  about the storage format.

- ModuleSettingsController::show(\$slug) returns the registered Schema +
  per-company values from CompanySetting (defaults flow through when nothing
  has been saved yet). update(\$slug) builds Laravel validator rules from
  the Schema's per-field rules arrays — with type-rule fallbacks for
  switch -> boolean, number -> numeric, multiselect -> array — silently
  drops unknown keys, and persists via CompanySetting::setSettings() under
  the module.{slug}.{key} prefix. Activation is instance-global, but
  settings are per-company: two companies on the same instance can
  configure the same activated module differently.

- routes/api.php mounts GET /api/v1/company-modules at the root of the
  company API group and GET/PUT /api/v1/modules/{slug}/settings inside the
  existing modules prefix.

Frontend:

- BaseSchemaForm.vue is the central new component — a generic schema-driven
  form renderer that maps schema fields to BaseInput / BaseTextarea /
  BaseSwitch / BaseMultiselect by type, and builds Vuelidate rules
  dynamically from each field's rules array (supports required, email, url,
  numeric, min:N, max:N). New fields are added by extending the type ->
  component map.

- CompanyModulesIndexView.vue fetches /company-modules and renders a card
  grid (with empty/loading states); CompanyModuleCard.vue is the per-row
  component with the Settings button. ModuleSettingsView.vue fetches
  /modules/{slug}/settings, hands {schema, values} to BaseSchemaForm, and
  posts back on submit.

- Company-context routes.ts is rebuilt after the previous commit relocated
  the marketplace browser away. It now declares modules.index +
  modules.settings, both gated by manage-module ability.

- New api/services/{companyModules,moduleSettings}.service.ts thin clients.

- lang/en.json adds modules.index.{description,empty_title,empty_description},
  modules.settings.{title,open,saved,not_found,none}, and
  modules.sidebar.section_title. The sidebar key is added here even though
  the dynamic sidebar rendering lands in the next commit — keeping all i18n
  additions in one file edit avoids hunk-splitting lang/en.json.
This commit is contained in:
Darko Gjorgjijoski
2026-04-09 00:29:36 +02:00
parent 84725b2dfa
commit e6eeacb6d4
13 changed files with 781 additions and 182 deletions

View File

@@ -0,0 +1,13 @@
import { client } from '../client'
import type { CompanyModuleSummary } from '@/scripts/features/company/modules/store'
export interface CompanyModulesListResponse {
data: CompanyModuleSummary[]
}
export const companyModulesService = {
async list(): Promise<CompanyModulesListResponse> {
const { data } = await client.get('/api/v1/company-modules')
return data
},
}

View File

@@ -0,0 +1,36 @@
import { client } from '../client'
export interface ModuleSettingsField {
key: string
type: 'text' | 'password' | 'textarea' | 'switch' | 'number' | 'select' | 'multiselect'
label: string
rules: string[]
default: unknown
options?: Record<string, string>
}
export interface ModuleSettingsSection {
title: string
fields: ModuleSettingsField[]
}
export interface ModuleSettingsSchema {
sections: ModuleSettingsSection[]
}
export interface ModuleSettingsResponse {
schema: ModuleSettingsSchema
values: Record<string, unknown>
}
export const moduleSettingsService = {
async fetch(slug: string): Promise<ModuleSettingsResponse> {
const { data } = await client.get(`/api/v1/modules/${slug}/settings`)
return data
},
async update(slug: string, values: Record<string, unknown>): Promise<{ success: boolean }> {
const { data } = await client.put(`/api/v1/modules/${slug}/settings`, values)
return data
},
}

View File

@@ -0,0 +1,233 @@
<template>
<form @submit.prevent="handleSubmit">
<div
v-for="(section, sectionIdx) in schema.sections"
:key="sectionIdx"
class="mb-10 last:mb-0"
>
<h3 class="text-base font-semibold text-heading mb-4">
{{ $t(section.title) }}
</h3>
<div class="grid grid-cols-1 gap-x-6 gap-y-5 md:grid-cols-2">
<BaseInputGroup
v-for="field in section.fields"
:key="field.key"
:label="$t(field.label)"
:required="isRequired(field)"
:error="errorFor(field.key)"
:class="{ 'md:col-span-2': isWideField(field) }"
>
<!-- text / password / number -->
<BaseInput
v-if="field.type === 'text' || field.type === 'password' || field.type === 'number'"
:type="field.type"
:model-value="(localValues[field.key] as string | number | null) ?? ''"
:invalid="!!errorFor(field.key)"
@update:model-value="setValue(field.key, $event)"
@blur="touchField(field.key)"
/>
<!-- textarea -->
<BaseTextarea
v-else-if="field.type === 'textarea'"
:model-value="(localValues[field.key] as string) ?? ''"
rows="4"
@update:model-value="setValue(field.key, $event)"
@blur="touchField(field.key)"
/>
<!-- switch -->
<BaseSwitch
v-else-if="field.type === 'switch'"
:model-value="!!localValues[field.key]"
@update:model-value="setValue(field.key, $event)"
/>
<!-- select -->
<BaseMultiselect
v-else-if="field.type === 'select'"
:model-value="localValues[field.key]"
:options="optionsArray(field)"
:allow-empty="!isRequired(field)"
track-by="value"
label="label"
@update:model-value="setValue(field.key, $event)"
/>
<!-- multiselect -->
<BaseMultiselect
v-else-if="field.type === 'multiselect'"
:model-value="localValues[field.key]"
:options="optionsArray(field)"
:multiple="true"
track-by="value"
label="label"
@update:model-value="setValue(field.key, $event)"
/>
</BaseInputGroup>
</div>
</div>
<div class="flex justify-end mt-8 pt-6 border-t border-line-default">
<BaseButton
type="submit"
:loading="isSaving"
:disabled="isSaving"
>
<template #left="slotProps">
<BaseIcon name="ArrowDownOnSquareIcon" :class="slotProps.class" />
</template>
{{ $t('general.save') }}
</BaseButton>
</div>
</form>
</template>
<script setup lang="ts">
import { reactive, ref, computed, watch } from 'vue'
import { useI18n } from 'vue-i18n'
import { useVuelidate } from '@vuelidate/core'
import {
required as requiredValidator,
email as emailValidator,
url as urlValidator,
minLength as minLengthValidator,
maxLength as maxLengthValidator,
numeric as numericValidator,
helpers,
} from '@vuelidate/validators'
import type {
ModuleSettingsField,
ModuleSettingsSchema,
} from '@/scripts/api/services/moduleSettings.service'
interface Props {
schema: ModuleSettingsSchema
values: Record<string, unknown>
isSaving?: boolean
}
const props = withDefaults(defineProps<Props>(), {
isSaving: false,
})
const emit = defineEmits<{
(e: 'submit', values: Record<string, unknown>): void
}>()
const { t } = useI18n()
// ---------------------------------------------------------------------------
// Local form state — a reactive copy of the incoming values, with defaults
// from the schema for any keys not yet stored.
// ---------------------------------------------------------------------------
const localValues = reactive<Record<string, unknown>>({})
function rebuildLocalValues(): void {
for (const key of Object.keys(localValues)) {
delete localValues[key]
}
for (const section of props.schema.sections) {
for (const field of section.fields) {
const incoming = props.values[field.key]
localValues[field.key] = incoming !== undefined && incoming !== null
? incoming
: field.default
}
}
}
watch(
() => [props.schema, props.values],
() => rebuildLocalValues(),
{ immediate: true, deep: true },
)
function setValue(key: string, value: unknown): void {
localValues[key] = value
}
function isRequired(field: ModuleSettingsField): boolean {
return field.rules.includes('required')
}
function isWideField(field: ModuleSettingsField): boolean {
return field.type === 'textarea' || field.type === 'multiselect'
}
function optionsArray(field: ModuleSettingsField): Array<{ value: string, label: string }> {
if (!field.options) return []
return Object.entries(field.options).map(([value, label]) => ({ value, label }))
}
// ---------------------------------------------------------------------------
// Vuelidate rules built dynamically from the schema's `rules` arrays.
// Supported rule strings: 'required', 'email', 'url', 'numeric',
// 'min:N' (string min length), 'max:N' (string max length).
// Unsupported rule strings are silently ignored client-side; the backend
// validator is the source of truth.
// ---------------------------------------------------------------------------
const dynamicRules = computed(() => {
const fieldRules: Record<string, Record<string, unknown>> = {}
for (const section of props.schema.sections) {
for (const field of section.fields) {
const rules: Record<string, unknown> = {}
for (const rule of field.rules) {
if (rule === 'required') {
rules.required = helpers.withMessage(t('validation.required'), requiredValidator)
} else if (rule === 'email') {
rules.email = helpers.withMessage(t('validation.email_incorrect'), emailValidator)
} else if (rule === 'url') {
rules.url = helpers.withMessage(t('validation.url_incorrect'), urlValidator)
} else if (rule === 'numeric') {
rules.numeric = helpers.withMessage(t('validation.numeric'), numericValidator)
} else if (rule.startsWith('min:')) {
const n = parseInt(rule.slice(4), 10)
if (!Number.isNaN(n)) {
rules.minLength = helpers.withMessage(
t('validation.name_min_length', { count: n }),
minLengthValidator(n),
)
}
} else if (rule.startsWith('max:')) {
const n = parseInt(rule.slice(4), 10)
if (!Number.isNaN(n)) {
rules.maxLength = helpers.withMessage(
t('validation.name_max_length', { count: n }),
maxLengthValidator(n),
)
}
}
}
if (Object.keys(rules).length > 0) {
fieldRules[field.key] = rules
}
}
}
return fieldRules
})
const v$ = useVuelidate(dynamicRules, localValues)
function errorFor(key: string): string | undefined {
const fieldState = (v$.value as Record<string, { $error: boolean, $errors: Array<{ $message: unknown }> }>)[key]
if (!fieldState || !fieldState.$error) return undefined
return String(fieldState.$errors[0]?.$message ?? '')
}
function touchField(key: string): void {
const fieldState = (v$.value as Record<string, { $touch?: () => void }>)[key]
fieldState?.$touch?.()
}
async function handleSubmit(): Promise<void> {
const valid = await v$.value.$validate()
if (!valid) return
emit('submit', { ...localValues })
}
</script>

View File

@@ -0,0 +1,61 @@
<template>
<div
class="
flex flex-col p-6 rounded-lg border border-line-default bg-surface-secondary
shadow-sm hover:shadow-md transition-shadow
"
>
<div class="flex items-start justify-between gap-3">
<div class="flex items-center gap-3">
<div class="
shrink-0 h-10 w-10 rounded-lg bg-primary-50 text-primary-600
flex items-center justify-center
">
<BaseIcon :name="iconName" class="h-5 w-5" />
</div>
<div>
<h3 class="text-base font-semibold text-heading">{{ data.name }}</h3>
<p class="text-xs text-muted">{{ $t('modules.version') }} {{ data.version }}</p>
</div>
</div>
</div>
<div class="mt-6 flex items-center justify-end">
<BaseButton
v-if="data.has_settings"
size="sm"
variant="primary-outline"
@click="goToSettings"
>
<template #left="slotProps">
<BaseIcon name="CogIcon" :class="slotProps.class" />
</template>
{{ $t('modules.settings.open') }}
</BaseButton>
<span v-else class="text-xs text-subtle italic">
{{ $t('modules.settings.none') }}
</span>
</div>
</div>
</template>
<script setup lang="ts">
import { computed } from 'vue'
import { useRouter } from 'vue-router'
import type { CompanyModuleSummary } from '../store'
interface Props {
data: CompanyModuleSummary
}
const props = defineProps<Props>()
const router = useRouter()
const iconName = computed<string>(() => {
return props.data.menu?.icon ?? 'PuzzlePieceIcon'
})
function goToSettings(): void {
router.push({ name: 'modules.settings', params: { slug: props.data.slug } })
}
</script>

View File

@@ -1,17 +1,14 @@
export { moduleRoutes } from './routes'
export { useModuleStore } from './store'
export { useCompanyModulesStore } from './store'
export type {
ModuleState,
ModuleStore,
ModuleDetailResponse,
ModuleDetailMeta,
InstallationStep,
CompanyModuleSummary,
CompanyModulesState,
} from './store'
// Views
export { default as ModuleIndexView } from './views/ModuleIndexView.vue'
export { default as ModuleDetailView } from './views/ModuleDetailView.vue'
export { default as CompanyModulesIndexView } from './views/CompanyModulesIndexView.vue'
export { default as ModuleSettingsView } from './views/ModuleSettingsView.vue'
// Components
export { default as ModuleCard } from './components/ModuleCard.vue'
export { default as CompanyModuleCard } from './components/CompanyModuleCard.vue'

View File

@@ -1,13 +1,25 @@
import type { RouteRecordRaw } from 'vue-router'
const ModuleIndexView = () => import('./views/ModuleIndexView.vue')
const ModuleDetailView = () => import('./views/ModuleDetailView.vue')
const CompanyModulesIndexView = () => import('./views/CompanyModulesIndexView.vue')
const ModuleSettingsView = () => import('./views/ModuleSettingsView.vue')
/**
* Company-context module routes.
*
* - `/admin/modules` — read-only Active Modules index, lists every module the
* super admin has activated on this instance with a "Settings" link.
* - `/admin/modules/:slug/settings` — schema-rendered settings form for a
* specific active module, backed by the InvoiceShelf\Modules\Registry::settingsFor()
* schema and CompanySetting persistence (per-company values).
*
* The marketplace browser (install/uninstall/activate) lives in the super-admin
* context at `/admin/administration/modules`, see features/admin/modules/routes.ts.
*/
export const moduleRoutes: RouteRecordRaw[] = [
{
path: 'modules',
name: 'modules.index',
component: ModuleIndexView,
component: CompanyModulesIndexView,
meta: {
requiresAuth: true,
ability: 'manage-module',
@@ -15,13 +27,13 @@ export const moduleRoutes: RouteRecordRaw[] = [
},
},
{
path: 'modules/:slug',
name: 'modules.view',
component: ModuleDetailView,
path: 'modules/:slug/settings',
name: 'modules.settings',
component: ModuleSettingsView,
meta: {
requiresAuth: true,
ability: 'manage-module',
title: 'modules.title',
title: 'modules.settings.title',
},
},
]

View File

@@ -1,180 +1,34 @@
import { defineStore } from 'pinia'
import { moduleService } from '../../../api/services/module.service'
import type {
Module,
ModuleReview,
ModuleFaq,
ModuleLink,
ModuleScreenshot,
} from '../../../types/domain/module'
import { companyModulesService } from '@/scripts/api/services/companyModules.service'
// ----------------------------------------------------------------
// Types
// ----------------------------------------------------------------
export interface ModuleDetailMeta {
modules: Module[]
export interface CompanyModuleSummary {
slug: string
name: string
version: string
has_settings: boolean
menu: { title: string, link: string, icon: string } | null
}
export interface ModuleDetailResponse {
data: Module
meta: ModuleDetailMeta
export interface CompanyModulesState {
modules: CompanyModuleSummary[]
isFetching: boolean
}
export interface InstallationStep {
translationKey: string
stepUrl: string
time: string | null
started: boolean
completed: boolean
}
// ----------------------------------------------------------------
// Store
// ----------------------------------------------------------------
export interface ModuleState {
currentModule: ModuleDetailResponse | null
modules: Module[]
apiToken: string | null
currentUser: {
api_token: string | null
}
enableModules: string[]
}
export const useModuleStore = defineStore('modules', {
state: (): ModuleState => ({
currentModule: null,
export const useCompanyModulesStore = defineStore('company-modules', {
state: (): CompanyModulesState => ({
modules: [],
apiToken: null,
currentUser: {
api_token: null,
},
enableModules: [],
isFetching: false,
}),
getters: {
salesTaxUSEnabled: (state): boolean =>
state.enableModules.includes('SalesTaxUS'),
installedModules: (state): Module[] =>
state.modules.filter((m) => m.installed),
},
actions: {
async fetchModules(): Promise<void> {
const response = await moduleService.list()
this.modules = response.data
},
async fetchModule(slug: string): Promise<ModuleDetailResponse> {
const response = await moduleService.get(slug)
const data = response as unknown as ModuleDetailResponse
if ((data as Record<string, unknown>).error === 'invalid_token') {
this.currentModule = null
this.modules = []
this.apiToken = null
this.currentUser.api_token = null
return data
this.isFetching = true
try {
const response = await companyModulesService.list()
this.modules = response.data
} finally {
this.isFetching = false
}
this.currentModule = data
return data
},
async checkApiToken(token: string): Promise<{ success: boolean; error?: string }> {
const response = await moduleService.checkToken(token)
return {
success: response.success ?? false,
error: response.error,
}
},
async disableModule(moduleName: string): Promise<{ success: boolean }> {
return moduleService.disable(moduleName)
},
async enableModule(moduleName: string): Promise<{ success: boolean }> {
return moduleService.enable(moduleName)
},
async installModule(
moduleName: string,
version: string,
onStepUpdate?: (step: InstallationStep) => void,
): Promise<boolean> {
const steps: InstallationStep[] = [
{
translationKey: 'modules.download_zip_file',
stepUrl: '/api/v1/modules/download',
time: null,
started: false,
completed: false,
},
{
translationKey: 'modules.unzipping_package',
stepUrl: '/api/v1/modules/unzip',
time: null,
started: false,
completed: false,
},
{
translationKey: 'modules.copying_files',
stepUrl: '/api/v1/modules/copy',
time: null,
started: false,
completed: false,
},
{
translationKey: 'modules.completing_installation',
stepUrl: '/api/v1/modules/complete',
time: null,
started: false,
completed: false,
},
]
let path: string | null = null
for (const step of steps) {
step.started = true
onStepUpdate?.(step)
try {
const stepFns: Record<string, () => Promise<Record<string, unknown>>> = {
'/api/v1/modules/download': () =>
moduleService.download({ module: moduleName, version, path: path ?? undefined } as never) as Promise<Record<string, unknown>>,
'/api/v1/modules/unzip': () =>
moduleService.unzip({ module: moduleName, version, path: path ?? undefined } as never) as Promise<Record<string, unknown>>,
'/api/v1/modules/copy': () =>
moduleService.copy({ module: moduleName, version, path: path ?? undefined } as never) as Promise<Record<string, unknown>>,
'/api/v1/modules/complete': () =>
moduleService.complete({ module: moduleName, version, path: path ?? undefined } as never) as Promise<Record<string, unknown>>,
}
const result = await stepFns[step.stepUrl]()
step.completed = true
onStepUpdate?.(step)
if ((result as Record<string, unknown>).path) {
path = (result as Record<string, unknown>).path as string
}
if (!(result as Record<string, unknown>).success) {
return false
}
} catch {
step.completed = true
onStepUpdate?.(step)
return false
}
}
return true
},
},
})
export type ModuleStore = ReturnType<typeof useModuleStore>

View File

@@ -0,0 +1,65 @@
<template>
<BasePage>
<BasePageHeader :title="$t('modules.title')">
<BaseBreadcrumb>
<BaseBreadcrumbItem :title="$t('general.home')" to="dashboard" />
<BaseBreadcrumbItem :title="$t('modules.module', 2)" to="#" active />
</BaseBreadcrumb>
</BasePageHeader>
<p class="mt-4 text-sm text-muted max-w-3xl">
{{ $t('modules.index.description') }}
</p>
<!-- Loading skeleton -->
<div
v-if="store.isFetching && store.modules.length === 0"
class="grid mt-8 w-full grid-cols-1 items-start gap-6 lg:grid-cols-2 xl:grid-cols-3"
>
<div v-for="n in 3" :key="n" class="h-32 bg-surface-tertiary rounded-lg animate-pulse" />
</div>
<!-- Empty state -->
<div
v-else-if="store.modules.length === 0"
class="mt-16 flex flex-col items-center justify-center text-center"
>
<div class="
h-16 w-16 rounded-full bg-surface-tertiary
flex items-center justify-center mb-4
">
<BaseIcon name="PuzzlePieceIcon" class="h-8 w-8 text-subtle" />
</div>
<h3 class="text-lg font-medium text-heading">
{{ $t('modules.index.empty_title') }}
</h3>
<p class="text-sm text-muted mt-2 max-w-md">
{{ $t('modules.index.empty_description') }}
</p>
</div>
<!-- Module list -->
<div
v-else
class="grid mt-8 w-full grid-cols-1 items-start gap-6 lg:grid-cols-2 xl:grid-cols-3"
>
<CompanyModuleCard
v-for="mod in store.modules"
:key="mod.slug"
:data="mod"
/>
</div>
</BasePage>
</template>
<script setup lang="ts">
import { onMounted } from 'vue'
import { useCompanyModulesStore } from '../store'
import CompanyModuleCard from '../components/CompanyModuleCard.vue'
const store = useCompanyModulesStore()
onMounted(() => {
store.fetchModules()
})
</script>

View File

@@ -0,0 +1,100 @@
<template>
<BasePage>
<BasePageHeader :title="pageTitle">
<BaseBreadcrumb>
<BaseBreadcrumbItem :title="$t('general.home')" to="dashboard" />
<BaseBreadcrumbItem :title="$t('modules.title')" to="/admin/modules" />
<BaseBreadcrumbItem :title="pageTitle" to="#" active />
</BaseBreadcrumb>
</BasePageHeader>
<div v-if="isFetching" class="mt-8 space-y-4">
<div class="h-6 bg-surface-tertiary rounded w-1/4 animate-pulse" />
<div class="h-12 bg-surface-tertiary rounded animate-pulse" />
<div class="h-12 bg-surface-tertiary rounded animate-pulse" />
</div>
<BaseCard v-else-if="schema" class="mt-6">
<BaseSchemaForm
:schema="schema"
:values="values"
:is-saving="isSaving"
@submit="onSubmit"
/>
</BaseCard>
<div v-else class="mt-16 text-center">
<p class="text-muted">{{ $t('modules.settings.not_found') }}</p>
</div>
</BasePage>
</template>
<script setup lang="ts">
import { ref, computed, onMounted, watch } from 'vue'
import { useRoute } from 'vue-router'
import { useI18n } from 'vue-i18n'
import {
moduleSettingsService,
type ModuleSettingsSchema,
} from '@/scripts/api/services/moduleSettings.service'
import { useNotificationStore } from '@/scripts/stores/notification.store'
import { handleApiError } from '@/scripts/utils/error-handling'
const route = useRoute()
const { t } = useI18n()
const notificationStore = useNotificationStore()
const schema = ref<ModuleSettingsSchema | null>(null)
const values = ref<Record<string, unknown>>({})
const isFetching = ref<boolean>(false)
const isSaving = ref<boolean>(false)
const slug = computed<string>(() => route.params.slug as string)
const pageTitle = computed<string>(() => {
// Modules supply their own translatable title via the schema first section
return schema.value?.sections[0]?.title
? t(schema.value.sections[0].title)
: t('modules.settings.title')
})
watch(slug, () => {
loadSettings()
})
onMounted(() => {
loadSettings()
})
async function loadSettings(): Promise<void> {
if (!slug.value) return
isFetching.value = true
try {
const response = await moduleSettingsService.fetch(slug.value)
schema.value = response.schema
values.value = response.values
} catch (err: unknown) {
schema.value = null
handleApiError(err)
} finally {
isFetching.value = false
}
}
async function onSubmit(formValues: Record<string, unknown>): Promise<void> {
isSaving.value = true
try {
await moduleSettingsService.update(slug.value, formValues)
values.value = formValues
notificationStore.showNotification({
type: 'success',
message: t('modules.settings.saved'),
})
} catch (err: unknown) {
handleApiError(err)
} finally {
isSaving.value = false
}
}
</script>