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.

resources/scripts/features/company/modules/components/CompanyModuleCard.vue

@@ -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>

resources/scripts/features/company/modules/index.ts

@@ -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'

resources/scripts/features/company/modules/routes.ts

@@ -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',
     },
   },
 ]

resources/scripts/features/company/modules/store.ts

@@ -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>

resources/scripts/features/company/modules/views/CompanyModulesIndexView.vue

@@ -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>

resources/scripts/features/company/modules/views/ModuleSettingsView.vue

@@ -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>