@saasicat/ui-vue 0.2.0

package/src/use-marketing-projections.ts

@@ -0,0 +1,160 @@
+// useMarketingProjections — Vue 3 composable over the
+// MarketingProjectionsController (`/admin/catalog/marketing-projections`).
+//
+// Unlike Bundle/BusinessType, **without versioning**: marketing edits
+// go live directly. The composable does not cache the list per filter tuple,
+// but reloads fresh on every `load()` — marketing maintenance is
+// low-frequency and consistency matters more than performance.
+
+import { ref, type Ref } from 'vue';
+import type {
+    CreateMarketingProjectionData,
+    MarketingProjectionFilter,
+    MarketingProjectionRow,
+    UpdateMarketingProjectionData,
+} from '@saasicat/types';
+import { defaultHttpClient, type HttpClient } from './types.js';
+
+export interface UseMarketingProjectionsOptions {
+    adminEndpoint: string;
+    http?: HttpClient;
+    getAuthToken?: () => string | null;
+    /** Filter that is active on `load()`. Can be changed via `setFilter()`. */
+    filter: MarketingProjectionFilter;
+    autoLoad?: boolean;
+}
+
+export class MarketingProjectionsApiError extends Error {
+    constructor(
+        public readonly status: number,
+        public readonly body: unknown,
+        message: string,
+    ) {
+        super(message);
+        this.name = 'MarketingProjectionsApiError';
+    }
+}
+
+export interface UseMarketingProjectionsResult {
+    projections: Ref<MarketingProjectionRow[]>;
+    filter: Ref<MarketingProjectionFilter>;
+    loading: Ref<boolean>;
+    error: Ref<Error | null>;
+
+    /** Changes the filter and reloads fresh. */
+    setFilter: (next: MarketingProjectionFilter) => Promise<void>;
+    load: () => Promise<void>;
+    create: (data: CreateMarketingProjectionData) => Promise<MarketingProjectionRow>;
+    update: (id: string, data: UpdateMarketingProjectionData) => Promise<MarketingProjectionRow>;
+    remove: (id: string) => Promise<void>;
+}
+
+export function useMarketingProjections(
+    options: UseMarketingProjectionsOptions,
+): UseMarketingProjectionsResult {
+    if (!options?.adminEndpoint) {
+        throw new Error('useMarketingProjections: `adminEndpoint` ist Pflicht.');
+    }
+    if (!options?.filter?.projectKey) {
+        throw new Error('useMarketingProjections: `filter.projectKey` ist Pflicht.');
+    }
+
+    const http = options.http ?? defaultHttpClient();
+    const projections = ref<MarketingProjectionRow[]>([]);
+    const filter = ref<MarketingProjectionFilter>({ ...options.filter });
+    const loading = ref(false);
+    const error = ref<Error | null>(null);
+
+    const baseUrl = `${options.adminEndpoint}/catalog/marketing-projections`;
+
+    function authHeaders(): Record<string, string> {
+        const token = options.getAuthToken?.();
+        return token ? { Authorization: `Bearer ${token}` } : {};
+    }
+
+    function buildListUrl(): string {
+        const params = new URLSearchParams();
+        params.set('projectKey', filter.value.projectKey);
+        if (filter.value.targetType) params.set('targetType', filter.value.targetType);
+        if (filter.value.targetVersionId)
+            params.set('targetVersionId', filter.value.targetVersionId);
+        if (filter.value.locale) params.set('locale', filter.value.locale);
+        return `${baseUrl}?${params.toString()}`;
+    }
+
+    async function fetchJson<T>(url: string, init?: Parameters<HttpClient>[1]): Promise<T | null> {
+        const res = await http(url, {
+            method: init?.method ?? 'GET',
+            headers: { 'content-type': 'application/json', ...authHeaders(), ...init?.headers },
+            body: init?.body,
+        });
+        if (res.status === 204) return null;
+        const body = await res.json().catch(() => null);
+        if (res.status >= 400) {
+            throw new MarketingProjectionsApiError(
+                res.status,
+                body,
+                `MarketingProjections-API antwortete mit HTTP ${res.status}`,
+            );
+        }
+        return body as T;
+    }
+
+    async function load(): Promise<void> {
+        loading.value = true;
+        error.value = null;
+        try {
+            const data = await fetchJson<MarketingProjectionRow[]>(buildListUrl());
+            projections.value = data ?? [];
+        } catch (err) {
+            error.value = err instanceof Error ? err : new Error(String(err));
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    async function setFilter(next: MarketingProjectionFilter): Promise<void> {
+        filter.value = { ...next };
+        await load();
+    }
+
+    async function create(data: CreateMarketingProjectionData): Promise<MarketingProjectionRow> {
+        const created = await fetchJson<MarketingProjectionRow>(baseUrl, {
+            method: 'POST',
+            body: JSON.stringify(data),
+        });
+        if (!created) {
+            throw new MarketingProjectionsApiError(0, null, 'Create gab keinen Body zurück');
+        }
+        // After create: reload the list (a unique tuple insert can
+        // affect the filter).
+        await load();
+        return created;
+    }
+
+    async function update(
+        id: string,
+        data: UpdateMarketingProjectionData,
+    ): Promise<MarketingProjectionRow> {
+        const updated = await fetchJson<MarketingProjectionRow>(`${baseUrl}/${id}`, {
+            method: 'PATCH',
+            body: JSON.stringify(data),
+        });
+        if (!updated) {
+            throw new MarketingProjectionsApiError(0, null, 'Update gab keinen Body zurück');
+        }
+        projections.value = projections.value.map((p) => (p.id === id ? updated : p));
+        return updated;
+    }
+
+    async function remove(id: string): Promise<void> {
+        await fetchJson<null>(`${baseUrl}/${id}`, { method: 'DELETE' });
+        projections.value = projections.value.filter((p) => p.id !== id);
+    }
+
+    if (options.autoLoad) {
+        void load();
+    }
+
+    return { projections, filter, loading, error, setFilter, load, create, update, remove };
+}

package/src/use-nav.ts

@@ -0,0 +1,33 @@
+// useNav — Vue 3 composable over NavBuilder.
+//
+// Wraps a reactive `Ref<AdminManifest | null>` (typically from
+// `useManifest()`) and returns reactive `routes` + `sidebar` ComputedRefs.
+
+import { computed, type ComputedRef, type Ref } from 'vue';
+import type { AdminManifest } from '@saasicat/types';
+import {
+    type BuildRouteEntry,
+    type NavBuilderOptions,
+    type SidebarSection,
+    buildRoutes,
+    buildSidebar,
+} from './nav-builder.js';
+
+export interface UseNavResult {
+    /** List of all routes available via the manifest — filtered by capabilities. */
+    routes: ComputedRef<BuildRouteEntry[]>;
+    /** Drawer items, grouped by navSection. */
+    sidebar: ComputedRef<SidebarSection[]>;
+}
+
+export function useNav(
+    manifest: Ref<AdminManifest | null>,
+    options: NavBuilderOptions = {},
+): UseNavResult {
+    const routes = computed<BuildRouteEntry[]>(() => {
+        if (!manifest.value) return [];
+        return buildRoutes(manifest.value, options);
+    });
+    const sidebar = computed<SidebarSection[]>(() => buildSidebar(routes.value));
+    return { routes, sidebar };
+}

package/src/use-plan-editor.ts

@@ -0,0 +1,162 @@
+// usePlanEditor — plan-editor discovery + validation for the SuperAdmin UI.
+//
+// Reads the full feature catalog including the `plannedOnly` marker from the
+// loaded manifest (`planCatalogSnapshot.features`) and provides:
+//
+//   1. `availableFeatures` — all features with reactive markers for the UI:
+//      `isPlannedOnly` (rendered in the UI as a "planned" chip), `isSelected`
+//      (in the current draft), `isInherited` (in the base plan, cannot be
+//      removed if `nonRegressive: true`).
+//
+//   2. `featuresByTier` — grouping by the `tier` convention (CORE,
+//      ADVANCED, PRO, BUSINESS, ENTERPRISE_ONLY) for the
+//      drawer rendering. Sorting as in the catalog.
+//
+//   3. `toggleFeature(key)` — toggles in the draft, but blocks `plannedOnly`
+//      features and (optionally) base-plan features on nonRegressive drafts.
+//
+//   4. `validateDraft()` — before the save: throws if the draft contains a
+//      plannedOnly feature (frontend mirror of the backend validation
+//      `assertNoPlannedOnlyFeatures` — prevents the UI from sending malformed
+//      POST bodies instead of showing the backend 400).
+//
+// What the platform does NOT do: the HTTP save itself. The consumer sends the
+// draft to `PATCH /api/v1/admin/plan-versions/:id` with the endpoint adapter
+// of its choice. Discovery + filter + validation lives centrally, persistence
+// project-specific.
+
+import { computed, ref, type ComputedRef, type Ref } from 'vue';
+import type { AdminManifest, FeatureDef, FeatureKey } from '@saasicat/types';
+
+export class PlannedOnlyFeatureError extends Error {
+    constructor(public readonly violations: FeatureKey[]) {
+        super(
+            `Folgende Features sind im Catalog als plannedOnly markiert und ` +
+                `dürfen nicht in einer Plan-Version stehen: ${violations.sort().join(', ')}.`,
+        );
+        this.name = 'PlannedOnlyFeatureError';
+    }
+}
+
+export interface FeatureRowMarkers {
+    /** Catalog definition (label, icon, tier, marker). */
+    def: FeatureDef;
+    /** Currently selected in the draft. */
+    isSelected: boolean;
+    /** Catalog marker `plannedOnly: true` — the UI shows it as roadmap, not bookable. */
+    isPlannedOnly: boolean;
+    /** In the base plan (inherited) — not removable on nonRegressive drafts. */
+    isInherited: boolean;
+    /** Computed: is the user allowed to toggle the feature? */
+    canToggle: boolean;
+}
+
+export interface UsePlanEditorOptions {
+    /** Initial selection — typically `draft.features` from PATCH preparation. */
+    initialFeatures?: FeatureKey[];
+    /** Features the base plan already contained; not removable under nonRegressive. */
+    baseFeatures?: FeatureKey[];
+    /** If `true`: base features are locked (default `true`, platform convention). */
+    nonRegressive?: boolean;
+}
+
+export interface UsePlanEditorResult {
+    /** Feature keys currently selected in the draft (Set for O(1) lookup). */
+    selectedFeatures: Ref<Set<FeatureKey>>;
+    /** Ordered list of all catalog features with UI markers. */
+    availableFeatures: ComputedRef<FeatureRowMarkers[]>;
+    /** Tier grouping for drawer sections (CORE, ADVANCED, PRO, …). */
+    featuresByTier: ComputedRef<Array<{ tier: string; rows: FeatureRowMarkers[] }>>;
+    /** Toggle without throwing: `plannedOnly` and locked features are ignored. */
+    toggleFeature: (key: FeatureKey) => void;
+    /** Pre-save validation. Throws `PlannedOnlyFeatureError` if disallowed keys are present. */
+    validateDraft: () => void;
+    /** Snapshot of the current selection for the PATCH body. */
+    snapshot: () => FeatureKey[];
+}
+
+const TIER_ORDER = ['CORE', 'ADVANCED', 'PRO', 'BUSINESS', 'ENTERPRISE_ONLY'];
+
+function tierWeight(tier: string | undefined): number {
+    if (!tier) return TIER_ORDER.length; // ungrouped goes to the end
+    const i = TIER_ORDER.indexOf(tier);
+    return i === -1 ? TIER_ORDER.length : i;
+}
+
+/**
+ * Plan-editor discovery + validation. The manifest provides the source of
+ * truth (catalog snapshot including the `plannedOnly` marker). The consumer
+ * builds the Vue component and uses this composable for state + filter.
+ */
+export function usePlanEditor(
+    manifest: AdminManifest,
+    options: UsePlanEditorOptions = {},
+): UsePlanEditorResult {
+    const baseSet = new Set(options.baseFeatures ?? []);
+    const nonRegressive = options.nonRegressive ?? true;
+
+    const selectedFeatures = ref<Set<FeatureKey>>(new Set(options.initialFeatures ?? []));
+
+    const catalogFeatures: FeatureDef[] = manifest.planCatalogSnapshot.features ?? [];
+    const plannedOnlySet = new Set(catalogFeatures.filter((f) => f.plannedOnly).map((f) => f.key));
+
+    const availableFeatures = computed<FeatureRowMarkers[]>(() => {
+        return catalogFeatures.map<FeatureRowMarkers>((def) => {
+            const isSelected = selectedFeatures.value.has(def.key);
+            const isPlannedOnly = !!def.plannedOnly;
+            const isInherited = baseSet.has(def.key);
+            const canToggle = !isPlannedOnly && (!nonRegressive || !isInherited || !isSelected);
+            return { def, isSelected, isPlannedOnly, isInherited, canToggle };
+        });
+    });
+
+    const featuresByTier = computed(() => {
+        const groups = new Map<string, FeatureRowMarkers[]>();
+        for (const row of availableFeatures.value) {
+            const tier = row.def.tier ?? 'OTHER';
+            const list = groups.get(tier) ?? [];
+            list.push(row);
+            groups.set(tier, list);
+        }
+        return [...groups.entries()]
+            .sort((a, b) => {
+                const wa = tierWeight(a[0]);
+                const wb = tierWeight(b[0]);
+                return wa !== wb ? wa - wb : a[0].localeCompare(b[0]);
+            })
+            .map(([tier, rows]) => ({ tier, rows }));
+    });
+
+    function toggleFeature(key: FeatureKey): void {
+        if (plannedOnlySet.has(key)) return; // roadmap feature, not bookable
+        const next = new Set(selectedFeatures.value);
+        if (next.has(key)) {
+            // On nonRegressive drafts an inherited feature must not be removed.
+            if (nonRegressive && baseSet.has(key)) return;
+            next.delete(key);
+        } else {
+            next.add(key);
+        }
+        selectedFeatures.value = next;
+    }
+
+    function validateDraft(): void {
+        const violations = [...selectedFeatures.value].filter((k) => plannedOnlySet.has(k));
+        if (violations.length > 0) {
+            throw new PlannedOnlyFeatureError(violations);
+        }
+    }
+
+    function snapshot(): FeatureKey[] {
+        return [...selectedFeatures.value].sort();
+    }
+
+    return {
+        selectedFeatures,
+        availableFeatures,
+        featuresByTier,
+        toggleFeature,
+        validateDraft,
+        snapshot,
+    };
+}

package/src/use-plan-versions.ts

@@ -0,0 +1,83 @@
+// usePlanVersionsCatalog — composable for the plan-versions page
+// (`<app> /admin/plans`).
+//
+// **Endpoint is mandatory** and is supplied by the app consumer, because
+// apps have different `globalPrefix` conventions
+// (e.g. `/api/admin/...` or `/api/v1/admin/...`).
+//
+// Platform pure functions (`assertDraftPublishable` etc. from
+// `@saasicat/nest/billing`) validate the drafts before the
+// publish POST.
+
+import { ref, type Ref } from 'vue';
+import { useApiList, type UseApiListOptions, type UseApiListResult } from './use-api-list.js';
+
+/**
+ * Generic filter shape for versions lists.
+ * `state`: 'draft' (publishedAt null), 'live' (publishedAt set, supersededAt null),
+ *          'superseded' (supersededAt set), 'all' (default).
+ */
+export interface PlanVersionListFilter {
+    state?: 'draft' | 'live' | 'superseded' | 'all';
+    /** PlanId (`'BASIC'`, `'STANDARD'`, …). */
+    planId?: string;
+}
+
+/**
+ * Generic versions row shape. Depending on the endpoint, the consumer backend
+ * returns slightly different fields; the platform composable takes the universal ones.
+ */
+export interface PlanVersionRow {
+    id: string;
+    version: number;
+    publishedAt: string | null;
+    supersededAt: string | null;
+    nonRegressive: boolean;
+    changeNote?: string;
+    [extra: string]: unknown;
+}
+
+export interface VersionsOptions {
+    /**
+     * Fully qualified versions-list endpoint including the app globalPrefix
+     * (`/api/admin/plan-versions`, `/api/v1/admin/plan-versions`, …). Mandatory.
+     */
+    endpoint: string;
+    filter?: Ref<PlanVersionListFilter>;
+    http?: UseApiListOptions<Record<string, unknown>>['http'];
+    getAuthToken?: () => string | null;
+    autoLoad?: boolean;
+}
+
+export interface VersionsResult extends UseApiListResult<PlanVersionRow> {
+    filter: Ref<PlanVersionListFilter>;
+}
+
+function buildVersionsComposable(label: string) {
+    return function (options: VersionsOptions): VersionsResult {
+        if (!options?.endpoint) {
+            throw new Error(
+                `${label}: \`endpoint\` ist Pflicht (z. B. "/api/admin/${label}" ` +
+                    `oder "/api/v1/admin/${label}"). Plattform hat keinen Default, ` +
+                    `weil Apps unterschiedliche globalPrefix-Konventionen haben.`,
+            );
+        }
+        const filter = options.filter ?? ref<PlanVersionListFilter>({});
+        const list = useApiList<PlanVersionRow>({
+            endpoint: options.endpoint,
+            filter: filter as unknown as Ref<Record<string, unknown>>,
+            http: options.http,
+            getAuthToken: options.getAuthToken,
+            autoLoad: options.autoLoad,
+        });
+        return { ...list, filter };
+    };
+}
+
+/**
+ * Read-only catalog view for PlanVersions (lift-and-shift from a
+ * consumer admin).
+ * Called `usePlanVersionsCatalog` since M6 Pack 2a, because `usePlanVersions`
+ * from `use-plans.ts` is now the lifecycle editor (createDraft/publish).
+ */
+export const usePlanVersionsCatalog = buildVersionsComposable('plan-versions');