@antelopejs/dms 0.0.1

package/frontend-vue/layers/dms-layout/app/composables/useSidebarWidgets.ts

@@ -0,0 +1,144 @@
+/**
+ * Where a {@link SidebarWidget} is mounted, independently of the module it is
+ * scoped to:
+ *
+ * - `ABOVE_SEARCH_BAR` — between the logo and the search button.
+ * - `BELOW_SEARCH_BAR` — under the search button, and under the module title
+ *   card as well while browsing inside a module.
+ */
+export const SidebarWidgetPosition = {
+  ABOVE_SEARCH_BAR: "above-search-bar",
+  BELOW_SEARCH_BAR: "below-search-bar",
+} as const;
+
+export type SidebarWidgetPosition =
+  (typeof SidebarWidgetPosition)[keyof typeof SidebarWidgetPosition];
+
+/**
+ * A free component rendered in the sidebar. Unlike a framed {@link AppWidget},
+ * the DMS adds no chrome: the component is mounted as-is, stacked with the
+ * other sidebar widgets in `order`, and receives the sidebar's `collapsed`
+ * state as a boolean prop so it can adapt to the narrow rail (components that
+ * don't care can ignore it).
+ *
+ * Placement and visibility are two independent axes. `position` says where the
+ * widget lands in the sidebar; `module` says when it renders at all — a global
+ * widget (no `module`) is hidden while browsing inside a module, a
+ * module-scoped one only shows inside its own module.
+ *
+ * Every field is serializable (no callables), so a widget can be registered
+ * from a regular (SSR-safe) plugin. Module scoping is declarative via `module`; any
+ * other conditional visibility is the widget's own responsibility: render
+ * nothing when it has nothing to show, or `unregister` (both `register` and
+ * `unregister` are idempotent / keyed by `id`).
+ */
+export interface SidebarWidget {
+  /** Unique key: dedup on `register` (upsert) and target of `unregister`. */
+  id: string;
+  /**
+   * Name of a global component mounted in the sidebar. It receives a
+   * `collapsed: boolean` prop reflecting the sidebar's collapsed state.
+   */
+  component: string;
+  /**
+   * Where the widget is mounted, whether or not it is scoped to a module.
+   * Defaults to the historical placement — `BELOW_SEARCH_BAR` for a
+   * module-scoped widget, `ABOVE_SEARCH_BAR` otherwise — so widgets written
+   * before the field existed keep their spot.
+   */
+  position?: SidebarWidgetPosition;
+  /**
+   * Stack order, ascending from the top, among the widgets sharing the same
+   * effective `position` — widgets sitting at different positions render at
+   * different spots, so `order` cannot interleave them. Defaults to `0`.
+   *
+   * Ties are broken by the widget's current index in the registry, not by when
+   * it was registered: re-registering an id updates it in place and keeps its
+   * index — even when the new `order` moves it to a different tie group — and
+   * `unregister` followed by `register` sends it to the end. Give tied widgets
+   * distinct `order` values when the stack has to be deterministic.
+   */
+  order?: number;
+  /**
+   * Only render while browsing inside this module (`/modules/<id>/**`). Absent
+   * means the global sidebar only: an unscoped widget is hidden while browsing
+   * inside any module. Either way the widget stays registered when out of
+   * scope — it just never mounts — so a layer can register once at boot from a
+   * universal plugin. An id that resolves to no installed module silently
+   * never renders. Scoping only picks the default `position`; a widget that
+   * declares one keeps it whether it is scoped or not.
+   */
+  module?: string;
+}
+
+interface UseSidebarWidgetsReturn {
+  widgets: Readonly<Ref<SidebarWidget[]>>;
+  register: (widget: SidebarWidget) => void;
+  unregister: (id: string) => void;
+}
+
+const KNOWN_POSITIONS = new Set<string>(Object.values(SidebarWidgetPosition));
+
+/**
+ * Position a widget renders at. A widget that declares no `position` — or one
+ * this DMS build doesn't know, which an older or untyped layer can still
+ * register — falls back to the placement used before `position` existed, so it
+ * always lands somewhere rather than silently vanishing.
+ */
+export const resolveSidebarWidgetPosition = (
+  widget: SidebarWidget,
+): SidebarWidgetPosition => {
+  if (widget.position && KNOWN_POSITIONS.has(widget.position)) {
+    return widget.position;
+  }
+  return widget.module
+    ? SidebarWidgetPosition.BELOW_SEARCH_BAR
+    : SidebarWidgetPosition.ABOVE_SEARCH_BAR;
+};
+
+/**
+ * Whether a widget renders while browsing the given module.
+ *
+ * The two axes are independent: this one answers *when*, the position answers
+ * *where*. A global widget (no `module`) shows only outside modules, and a
+ * scoped one only inside its own — an exact match either way, so a widget
+ * scoped to one module can never appear in another.
+ *
+ * @param widget Widget being considered
+ * @param currentModuleId Module being browsed; `null` or `undefined` outside
+ *   any module — the sidebar passes an optional chain, so both reach here
+ */
+export const isSidebarWidgetVisible = (
+  widget: SidebarWidget,
+  currentModuleId: string | null | undefined,
+): boolean => (widget.module ?? null) === (currentModuleId ?? null);
+
+/**
+ * Registry of free components rendered by the DMS in the sidebar — above or
+ * below the search button, as each widget declares. See {@link SidebarWidget}
+ * for the contract and {@link useAppWidgets} for the framed page-dock
+ * alternative.
+ */
+export const useSidebarWidgets = (): UseSidebarWidgetsReturn => {
+  const widgets = useDmsState<SidebarWidget[]>("dms-sidebar-widgets", () => []);
+
+  function register(widget: SidebarWidget): void {
+    // Re-registering upserts in place, so a widget swapping its component
+    // keeps its rank among the widgets sharing its order.
+    const known = widgets.value.findIndex((entry) => entry.id === widget.id);
+    const next = [...widgets.value];
+    if (known === -1) {
+      next.push(widget);
+    } else {
+      next[known] = widget;
+    }
+    next.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+    widgets.value = next;
+  }
+
+  function unregister(id: string): void {
+    widgets.value = widgets.value.filter((entry) => entry.id !== id);
+  }
+
+  return { widgets, register, unregister };
+};

package/frontend-vue/layers/dms-layout/app/custom-layouts/DefaultLayout.vue

@@ -0,0 +1,55 @@
+<script setup lang="ts">
+import Container from "../build/components/layout/Container.vue";
+import PageHeader from "../build/components/layout/PageHeader.vue";
+import DashboardSidebar from "../build/components/layout/DashboardSidebar.vue";
+import DashboardHeader from "../build/components/layout/DashboardHeader.vue";
+
+interface Props {
+  fullWidth?: boolean;
+  hideHeader?: boolean;
+  icon?: string;
+  title?: string;
+  description?: string;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  fullWidth: true,
+  hideHeader: false,
+  icon: "i-ph-file",
+  title: undefined,
+  description: undefined,
+});
+</script>
+
+<template>
+  <UDashboardGroup data-dms-persistent-shell>
+    <DashboardSidebar />
+
+    <UDashboardPanel>
+      <template #header>
+        <DashboardHeader />
+      </template>
+
+      <template #body>
+        <Container
+          data-dms-page-region
+          data-dms-page-content
+          :full-width="props.fullWidth"
+        >
+          <PageHeader
+            v-if="props.title && !props.hideHeader"
+            :icon="props.icon || 'i-ph-file'"
+            :title="props.title"
+            :description="props.description"
+            class="pt-6 pb-7"
+          />
+          <slot />
+        </Container>
+      </template>
+
+      <template #footer>
+        <DmsAppWidgetsDock />
+      </template>
+    </UDashboardPanel>
+  </UDashboardGroup>
+</template>

package/frontend-vue/layers/dms-layout/app/custom-layouts/EmptyLayout.vue

@@ -0,0 +1,23 @@
+<script setup lang="ts">
+import Footer from "../build/components/layout/Footer.vue";
+
+defineOptions({
+  inheritAttrs: false,
+});
+</script>
+
+<template>
+  <div class="flex min-h-screen flex-col">
+    <header class="my-16 flex w-full justify-center">
+      <DmsAppLogo class="h-20 w-auto" />
+    </header>
+
+    <!-- Named so a module's overlay can measure the region a page occupies,
+         the same way DefaultLayout marks its container. -->
+    <main class="flex-1" data-dms-page-content>
+      <slot />
+    </main>
+
+    <Footer />
+  </div>
+</template>

package/frontend-vue/layers/dms-layout/app/custom-pages/modules.vue

@@ -0,0 +1,114 @@
+<script setup lang="ts">
+const SKELETON_PLACEHOLDER_COUNT = 6;
+
+const isOwner = useIsOwner();
+const homepage = useHomepage();
+const siteLayout = useSiteLayout();
+const modulesListing = useModulesListing();
+const moduleHistory = useModuleHistory();
+const { processI18n } = useTranslation();
+
+if (!siteLayout.siteLayout.value) {
+  await siteLayout.loadSiteLayout();
+}
+
+if (!isOwner.value) {
+  await navigateDms(homepage, { replace: true });
+}
+
+if (modulesListing.modules.value === undefined) {
+  await modulesListing.loadModulesListing();
+}
+
+const accessibleModules = computed(() =>
+  (modulesListing.modules.value ?? []).filter(
+    (entry) => entry.hasAccess === true,
+  ),
+);
+
+const skeletonItems = computed(() =>
+  Array.from({ length: SKELETON_PLACEHOLDER_COUNT }, (_, index) => index),
+);
+
+const isInitiallyLoading = computed(
+  () =>
+    modulesListing.isLoading.value &&
+    modulesListing.modules.value === undefined,
+);
+
+async function handleSelectModule(
+  entry: ModuleInfo & { hasAccess: boolean; landingSlug: string },
+): Promise<void> {
+  const lastSlug = moduleHistory.getLast(entry.id);
+  const target = lastSlug ?? entry.landingSlug;
+  await navigateDms(target);
+}
+</script>
+
+<template>
+  <div class="space-y-6 pb-20">
+    <div v-if="modulesListing.loadingError.value" class="text-error">
+      {{ modulesListing.loadingError.value }}
+    </div>
+
+    <div
+      v-else-if="isInitiallyLoading"
+      class="grid gap-5 sm:grid-cols-2 lg:grid-cols-3"
+    >
+      <div
+        v-for="placeholder in skeletonItems"
+        :key="placeholder"
+        class="dms-card flex flex-col gap-4 p-6"
+      >
+        <USkeleton class="size-14 rounded-xl" />
+        <div class="space-y-2">
+          <USkeleton class="h-5 w-1/2" />
+          <USkeleton class="h-3 w-full" />
+          <USkeleton class="h-3 w-2/3" />
+        </div>
+      </div>
+    </div>
+
+    <div
+      v-else-if="accessibleModules.length === 0"
+      class="text-dimmed py-12 text-center"
+    >
+      {{ $t("modules.empty") }}
+    </div>
+
+    <div v-else class="grid gap-5 sm:grid-cols-2 lg:grid-cols-3">
+      <button
+        v-for="entry in accessibleModules"
+        :key="entry.id"
+        type="button"
+        class="group dms-card hover:border-primary hover:ring-primary/30 hover:bg-elevated/50 focus-visible:ring-primary relative flex cursor-pointer flex-col gap-4 overflow-hidden p-6 text-left transition-all duration-200 hover:-translate-y-0.5 hover:shadow-lg hover:ring-2 focus-visible:ring-2 focus-visible:outline-none"
+        @click="handleSelectModule(entry)"
+      >
+        <div
+          class="from-primary/15 to-primary/5 ring-primary/20 flex size-14 items-center justify-center rounded-xl bg-gradient-to-br ring-1"
+        >
+          <UIcon :name="entry.icon" class="text-primary size-7" />
+        </div>
+
+        <div class="min-w-0 flex-1 space-y-1">
+          <h3 class="text-highlighted text-base leading-tight font-semibold">
+            {{ processI18n(entry.title) }}
+          </h3>
+          <p class="text-dimmed line-clamp-2 text-sm leading-relaxed">
+            {{ processI18n(entry.description) }}
+          </p>
+        </div>
+
+        <div
+          class="text-muted group-hover:text-primary mt-1 flex items-center gap-1.5 text-xs font-medium transition-colors"
+        >
+          <span>{{ $t("modules.open") }}</span>
+          <UIcon
+            name="i-ph-arrow-right"
+            class="size-3.5 transition-transform group-hover:translate-x-0.5"
+          />
+        </div>
+      </button>
+    </div>
+  </div>
+</template>

package/frontend-vue/layers/dms-layout/app/custom-pages/settings/appearance.vue

@@ -0,0 +1,174 @@
+<script setup lang="ts">
+import ThemePreview from "../../build/components/pages/settings/theme/ThemePreview.vue";
+import ScalePreview from "../../build/components/pages/settings/theme/ScalePreview.vue";
+import CssVariablesList from "../../build/components/pages/settings/theme/CssVariablesList.vue";
+
+const colorOptions = [
+  {
+    value: "system",
+    label: "$page.settings.appearance.system",
+  },
+  {
+    value: "light",
+    label: "$page.settings.appearance.light",
+  },
+  {
+    value: "dark",
+    label: "$page.settings.appearance.dark",
+  },
+];
+
+const scaleOptions: ScaleOption[] = [
+  {
+    value: "small",
+    label: "$page.settings.appearance.scale_small",
+    hint: "$page.settings.appearance.scale_small_hint",
+  },
+  {
+    value: "normal",
+    label: "$page.settings.appearance.scale_normal",
+    hint: "$page.settings.appearance.scale_normal_hint",
+  },
+  {
+    value: "large",
+    label: "$page.settings.appearance.scale_large",
+    hint: "$page.settings.appearance.scale_large_hint",
+  },
+];
+
+const colorMode = useColorMode();
+const interfaceScale = useInterfaceScale();
+const { processI18n } = useTranslation();
+</script>
+
+<template>
+  <div class="space-y-5 pb-16">
+    <DmsCard as="section" class="grid gap-x-8 gap-y-6">
+      <div class="space-y-1">
+        <h2 class="text-default text-base font-semibold sm:text-sm">
+          {{ $t("page.settings.appearance.theme_title") }}
+        </h2>
+
+        <p data-slot="text" class="text-dimmed text-base sm:text-sm">
+          {{ $t("page.settings.appearance.theme_description") }}
+        </p>
+      </div>
+
+      <div class="grid grid-cols-1 gap-4 sm:grid-cols-3">
+        <label
+          v-for="(option, index) in colorOptions"
+          :key="`color-option-${index}`"
+          class="group bg-elevated relative flex cursor-pointer flex-col overflow-hidden rounded-xl transition-all"
+          :class="
+            colorMode.preference === option.value
+              ? 'outline-primary outline-2 outline-offset-2'
+              : 'ring-default hover:ring-accented ring hover:-translate-y-0.5'
+          "
+        >
+          <input
+            v-model="colorMode.preference"
+            type="radio"
+            :value="option.value"
+            class="sr-only"
+          />
+
+          <div class="flex justify-center p-4 pb-3">
+            <ThemePreview
+              :mode="option.value"
+              class="ring-default/60 h-28 w-full rounded-lg ring"
+            />
+          </div>
+
+          <div
+            class="border-default flex items-center gap-2 border-t px-3 py-2.5"
+          >
+            <span
+              class="ring-accented grid size-4 shrink-0 place-items-center rounded-full ring ring-inset"
+              :class="
+                colorMode.preference === option.value
+                  ? 'bg-primary ring-primary'
+                  : ''
+              "
+            >
+              <span
+                v-if="colorMode.preference === option.value"
+                class="bg-default size-1.5 rounded-full"
+              />
+            </span>
+
+            <span class="text-default truncate text-sm font-medium">
+              {{ processI18n(option.label) }}
+            </span>
+          </div>
+        </label>
+      </div>
+    </DmsCard>
+
+    <DmsCard as="section" class="grid gap-x-8 gap-y-6">
+      <div class="space-y-1">
+        <h2 class="text-default text-base font-semibold sm:text-sm">
+          {{ $t("page.settings.appearance.scale_title") }}
+        </h2>
+
+        <p data-slot="text" class="text-dimmed text-base sm:text-sm">
+          {{ $t("page.settings.appearance.scale_description") }}
+        </p>
+      </div>
+
+      <div class="grid grid-cols-1 gap-4 sm:grid-cols-3">
+        <label
+          v-for="(option, index) in scaleOptions"
+          :key="`scale-option-${index}`"
+          class="group bg-elevated relative flex cursor-pointer flex-col overflow-hidden rounded-xl transition-all"
+          :class="
+            interfaceScale === option.value
+              ? 'outline-primary outline-2 outline-offset-2'
+              : 'ring-default hover:ring-accented ring hover:-translate-y-0.5'
+          "
+        >
+          <input
+            v-model="interfaceScale"
+            type="radio"
+            :value="option.value"
+            class="sr-only"
+          />
+
+          <div class="flex justify-center p-4 pb-3">
+            <ScalePreview
+              :scale="option.value"
+              class="ring-default/60 h-28 w-full rounded-lg ring"
+            />
+          </div>
+
+          <div
+            class="border-default flex items-center gap-2 border-t px-3 py-2.5"
+          >
+            <span
+              class="ring-accented grid size-4 shrink-0 place-items-center rounded-full ring ring-inset"
+              :class="
+                interfaceScale === option.value ? 'bg-primary ring-primary' : ''
+              "
+            >
+              <span
+                v-if="interfaceScale === option.value"
+                class="bg-default size-1.5 rounded-full"
+              />
+            </span>
+
+            <span class="text-default truncate text-sm font-medium">
+              {{ processI18n(option.label) }}
+            </span>
+
+            <span class="text-dimmed ml-auto truncate font-mono text-[10px]">
+              {{ processI18n(option.hint) }}
+            </span>
+          </div>
+        </label>
+      </div>
+    </DmsCard>
+
+    <DmsCard as="section">
+      <CssVariablesList />
+    </DmsCard>
+  </div>
+</template>

package/frontend-vue/layers/dms-layout/app/custom-pages/settings/index.vue

@@ -0,0 +1,164 @@
+<script setup lang="ts">
+const siteLayout = useSiteLayout();
+if (!siteLayout.siteLayout.value) {
+  await siteLayout.loadSiteLayout();
+}
+
+if (siteLayout.loadingError && siteLayout.loadingError.value) {
+  throw createError({
+    statusCode: HTTP_INTERNAL_SERVER_ERROR,
+    statusMessage: "Error loading site layout",
+    message: siteLayout.loadingError.value || "Unknown error occurred",
+  });
+}
+
+interface SettingsOption {
+  name: string;
+  description: string;
+  icon: string;
+  to: string;
+}
+
+interface Group {
+  groupName: string;
+  groupIcon?: string;
+  options: SettingsOption[];
+}
+
+interface PageWithParent {
+  page: typeof siteLayout.siteLayoutTree.value;
+  parent: typeof siteLayout.siteLayoutTree.value;
+}
+
+interface FindSettingsPagesResult {
+  results: PageWithParent[];
+  hasSettingsChildren: boolean;
+}
+
+function findSettingsPages(
+  node: typeof siteLayout.siteLayoutTree.value,
+  parent: typeof siteLayout.siteLayoutTree.value | null = null,
+): FindSettingsPagesResult {
+  if (!node) return { results: [], hasSettingsChildren: false };
+
+  const results: PageWithParent[] = [];
+  let hasSettingsChildrenInSubtree = false;
+
+  if (node.children) {
+    for (const child of Object.values(node.children)) {
+      if (child) {
+        const childResult = findSettingsPages(child, node);
+        results.push(...childResult.results);
+        if (childResult.hasSettingsChildren) {
+          hasSettingsChildrenInSubtree = true;
+        }
+      }
+    }
+  }
+
+  const isSettingsPage = !!(
+    node.layoutUrl &&
+    node.fullId.startsWith("settings.") &&
+    node.fullId !== "settings.settings"
+  );
+
+  if (isSettingsPage) {
+    if (parent && node.hasAccess !== false && !hasSettingsChildrenInSubtree) {
+      results.push({ page: node, parent });
+    }
+    hasSettingsChildrenInSubtree = true;
+  }
+
+  return { results, hasSettingsChildren: hasSettingsChildrenInSubtree };
+}
+
+function buildGroupFromPages(
+  parent: NonNullable<typeof siteLayout.siteLayoutTree.value>,
+  pages: NonNullable<typeof siteLayout.siteLayoutTree.value>[],
+): (Group & { order: number }) | null {
+  if (parent.hasAccess === false) return null;
+
+  const sortedPages = pages
+    .sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
+    .map((page) => ({
+      name: page.displayName,
+      description: page.description || "",
+      icon: page.icon || "i-ph-gear",
+      to: page.fullSlug,
+    }));
+
+  return {
+    groupName: parent.displayName,
+    groupIcon: parent.icon,
+    options: sortedPages,
+    order: parent.order ?? 0,
+  };
+}
+
+const groups = computed<Group[]>(() => {
+  if (!siteLayout.siteLayoutTree.value) return [];
+
+  const tree = siteLayout.siteLayoutTree.value;
+  if (!tree) return [];
+
+  const { results: pagesWithParents } = findSettingsPages(tree);
+
+  const groupsMap = new Map<
+    string,
+    { parent: typeof tree; pages: (typeof tree)[] }
+  >();
+
+  for (const { page, parent } of pagesWithParents) {
+    if (!page || !parent) continue;
+    const parentId = parent.fullId;
+    if (!groupsMap.has(parentId)) {
+      groupsMap.set(parentId, { parent, pages: [] });
+    }
+    groupsMap.get(parentId)!.pages.push(page);
+  }
+
+  return Array.from(groupsMap.values())
+    .map(({ parent, pages }) => buildGroupFromPages(parent, pages))
+    .filter((item): item is Group & { order: number } => item !== null)
+    .sort((a, b) => a.order - b.order)
+    .map(({ groupName, groupIcon, options }) => ({
+      groupName,
+      groupIcon,
+      options,
+    }));
+});
+
+const { processI18n } = useTranslation();
+</script>
+
+<template>
+  <div class="space-y-8 pb-20">
+    <section
+      v-for="(group, index) in groups"
+      :key="`group-${index}`"
+      class="pb-14"
+    >
+      <h2
+        class="text-muted flex items-center gap-2.5 pb-6 text-sm font-medium tracking-wider uppercase"
+      >
+        <Icon
+          v-if="group.groupIcon"
+          :name="group.groupIcon"
+          class="text-primary size-4.5"
+        />
+        {{ processI18n(group.groupName) }}
+      </h2>
+
+      <div class="grid gap-6 sm:grid-cols-2 lg:grid-cols-3">
+        <DmsNavCard
+          v-for="(option, optIndex) in group.options"
+          :key="`option-${index}-${optIndex}`"
+          :to="option.to"
+          :icon="option.icon"
+          :title="processI18n(option.name)"
+          :description="processI18n(option.description)"
+        />
+      </div>
+    </section>
+  </div>
+</template>

package/frontend-vue/layers/dms-layout/app/custom-pages/settings/notifications.vue

@@ -0,0 +1,15 @@
+<script setup lang="ts">
+import NotificationPreferencesForm from "../../build/components/pages/settings/notification/NotificationPreferencesForm.vue";
+import NotificationsList from "../../build/components/pages/settings/notification/NotificationsList.vue";
+</script>
+
+<template>
+  <div class="space-y-5 pb-16">
+    <DmsCard as="section">
+      <NotificationPreferencesForm />
+    </DmsCard>
+    <DmsCard as="section">
+      <NotificationsList />
+    </DmsCard>
+  </div>
+</template>