@octabits-io/nuxt-ui-kit 0.2.0 → 0.3.0

package/dist/i18n/index.js

@@ -0,0 +1,80 @@
+//#region src/i18n/index.ts
+const kitMessagesEn = {
+	errors: {
+		internal_server_error: "An unexpected error occurred",
+		not_found: "Resource not found",
+		forbidden: "Permission denied",
+		validation_error: "Validation error",
+		unique_violation: "This value already exists",
+		foreign_key_violation: "Referenced record does not exist",
+		service_unavailable: "Service temporarily unavailable. Please try again later."
+	},
+	auth: {
+		sessionRenewFailedTitle: "Session refresh failed",
+		sessionRenewFailedDescription: "We couldn't refresh your session. You may need to sign in again.",
+		sessionExpiredTitle: "Session expired",
+		sessionExpiredDescription: "Your session has expired. Please sign in again.",
+		signingIn: "Completing sign in..."
+	},
+	localeField: {
+		translate: "Translate empty languages with AI",
+		translateDone: "No translations added | {count} translation added | {count} translations added",
+		inheritsBaseLocale: "Inherits the base locale",
+		translationStatus: {
+			complete: "All translations complete",
+			missing: "Missing translations — {details}"
+		}
+	},
+	pageChrome: {
+		back: "Back",
+		moreActions: "More actions",
+		help: "Help"
+	}
+};
+const kitMessagesDe = {
+	errors: {
+		internal_server_error: "Ein unerwarteter Fehler ist aufgetreten",
+		not_found: "Ressource nicht gefunden",
+		forbidden: "Zugriff verweigert",
+		validation_error: "Validierungsfehler",
+		unique_violation: "Dieser Wert existiert bereits",
+		foreign_key_violation: "Der referenzierte Datensatz existiert nicht",
+		service_unavailable: "Dienst vorübergehend nicht verfügbar. Bitte versuche es später erneut."
+	},
+	auth: {
+		sessionRenewFailedTitle: "Sitzung konnte nicht erneuert werden",
+		sessionRenewFailedDescription: "Wir konnten deine Sitzung nicht erneuern. Eventuell musst du dich neu anmelden.",
+		sessionExpiredTitle: "Sitzung abgelaufen",
+		sessionExpiredDescription: "Deine Sitzung ist abgelaufen. Bitte melde dich erneut an.",
+		signingIn: "Anmeldung wird abgeschlossen..."
+	},
+	localeField: {
+		translate: "Fehlende Sprachen mit KI übersetzen",
+		translateDone: "Keine Übersetzungen eingefügt | {count} Übersetzung eingefügt | {count} Übersetzungen eingefügt",
+		inheritsBaseLocale: "Übernimmt die Basissprache",
+		translationStatus: {
+			complete: "Alle Übersetzungen vollständig",
+			missing: "Fehlende Übersetzungen — {details}"
+		}
+	},
+	pageChrome: {
+		back: "Zurück",
+		moreActions: "Weitere Aktionen",
+		help: "Hilfe"
+	}
+};
+const kitMessagesDeFormal = {
+	errors: {
+		...kitMessagesDe.errors,
+		service_unavailable: "Dienst vorübergehend nicht verfügbar. Bitte versuchen Sie es später erneut."
+	},
+	auth: {
+		...kitMessagesDe.auth,
+		sessionRenewFailedDescription: "Wir konnten Ihre Sitzung nicht erneuern. Eventuell müssen Sie sich neu anmelden.",
+		sessionExpiredDescription: "Ihre Sitzung ist abgelaufen. Bitte melden Sie sich erneut an."
+	},
+	localeField: kitMessagesDe.localeField,
+	pageChrome: kitMessagesDe.pageChrome
+};
+//#endregion
+export { kitMessagesDe, kitMessagesDeFormal, kitMessagesEn };

package/dist/index.d.ts

@@ -1,299 +1,4 @@
-import { UserManager, UserManagerSettings, UserProfile } from "oidc-client-ts";
-import { ComputedRef, Ref } from "vue";
-import { Treaty } from "@elysiajs/eden";
-import { Elysia } from "elysia";
-//#region src/auth/oidc.d.ts
-/** Issuer + client id, resolved at first use (client-side runtime config). */
-interface OidcClientConfig {
-  issuerUrl: string;
-  clientId: string;
-}
-interface UserManagerFactoryOptions {
-  /**
-   * Resolve the issuer/client pair lazily — typically from a runtime-injected
-   * config object (e.g. a K8s-entrypoint `window.__APP_CONFIG__`) falling back
-   * to the app's build-time config.
-   */
-  getConfig: () => OidcClientConfig;
-  /** OAuth scopes requested on the initial signin. */
-  scope: string;
-  /**
-   * Scopes sent on the refresh-token grant when the IdP restricts them to a
-   * subset of the signin scopes (see `ZITADEL_REFRESH_TOKEN_ALLOWED_SCOPE`).
-   */
-  refreshTokenAllowedScope?: string;
-  /** Path the IdP redirects back to after signin. Default `/auth/callback`. */
-  redirectPath?: string;
-  /** Path the IdP redirects to after logout. Default `/login`. */
-  postLogoutRedirectPath?: string;
-  /** Default `true`. */
-  automaticSilentRenew?: boolean;
-  /** Raw oidc-client-ts settings escape hatch, applied last. */
-  settings?: Partial<UserManagerSettings>;
-  /** Called when issuer/client resolve empty. Default `console.error`. */
-  onMissingConfig?: (message: string) => void;
-}
-/**
- * Lazily-created `UserManager` singleton bound to `window.localStorage`.
- * Call the returned getter from plugins/stores/composables — the manager is
- * constructed on first call (client-side only; requires `window`).
- */
-declare function createUserManagerFactory(options: UserManagerFactoryOptions): () => UserManager;
-type StaleKeyStorage = Pick<Storage, 'length' | 'key' | 'removeItem'>;
-/**
- * Remove any `oidc.user:` storage keys that don't belong to the current
- * authority+clientId — leftovers from environment switches would otherwise
- * shadow or bloat the session storage.
- */
-declare function removeStaleOidcKeys(authority: string, clientId: string, storage?: StaleKeyStorage): void;
-/** Refresh tokens fail unrecoverably with these OIDC error codes — user must re-auth. */
-declare function isUnrecoverableRenewError(message: string): boolean;
-interface LoginRedirectorOptions {
-  getUserManager: () => UserManager;
-  /** Fallback login page for when `signinRedirect` itself fails. Default `/login`. */
-  loginPath?: string;
-  /**
-   * Paths where redirecting to login would loop (the login/callback pages
-   * themselves). Default: `loginPath` and anything under `/auth/`.
-   */
-  isAuthRoute?: (path: string) => boolean;
-  /** Default `console.error`. */
-  log?: (message: string, detail?: unknown) => void;
-}
-/**
- * Build a `redirectToLogin()` that starts an OIDC signin redirect carrying the
- * current path as returnUrl state, with a plain `/login?redirect=` navigation
- * fallback when the IdP redirect cannot even be started. No-ops on auth routes.
- */
-declare function createLoginRedirector(options: LoginRedirectorOptions): () => Promise<void>;
-/**
- * A user-facing session event the app should surface (toast/banner). The kit
- * classifies; presentation and copy stay in the app.
- *
- * - `renew-failed` — silent renew failed recoverably (next renew may succeed).
- * - `session-expired` — the session is gone; a login redirect follows.
- */
-type SessionNotice = {
-  kind: 'renew-failed';
-  error: Error;
-} | {
-  kind: 'session-expired';
-  error?: Error;
-};
-interface SessionLifecycleHandlers {
-  /** Start re-authentication (typically from {@link createLoginRedirector}). */
-  redirectToLogin: () => void | Promise<void>;
-  /** Surface a notice to the user (toast). Optional — omit for headless use. */
-  notify?: (notice: SessionNotice) => void;
-  /** Clear app-side session state (e.g. reset the auth store's user). */
-  onSessionLost?: () => void;
-  /** Default `console.warn`. */
-  log?: (message: string, detail?: unknown) => void;
-}
-/**
- * Wire oidc-client-ts session events to app callbacks:
- *
- * - silent-renew error → `notify` (`renew-failed`, or `session-expired` when the
- *   error is unrecoverable — see {@link isUnrecoverableRenewError}); an
- *   unrecoverable error also triggers the login redirect
- * - access token expired without renewal → `notify(session-expired)` +
- *   `onSessionLost` + login redirect
- * - back-channel signout at the IdP → `onSessionLost` + login redirect (no notice
- *   — the user initiated it elsewhere)
- *
- * Returns a detach function.
- */
-declare function attachSessionLifecycleHandlers(userManager: UserManager, handlers: SessionLifecycleHandlers): () => void;
-//#endregion
-//#region src/auth/zitadel.d.ts
-/**
- * Zitadel scope presets for {@link createUserManagerFactory}.
- *
- * The URN scopes request the resource-owner (organization) claim and the
- * project role grants; `offline_access` requests a refresh token.
- */
-declare const ZITADEL_ORG_PROJECT_SCOPE = "openid profile email urn:zitadel:iam:user:resourceowner urn:zitadel:iam:org:project:roles offline_access";
-/**
- * Zitadel only accepts standard OIDC scopes on the refresh-token grant —
- * sending `offline_access` or the `urn:zitadel:*` scopes returns
- * `invalid_scope` even though they were granted at the initial auth. The
- * URN-based claims still need to land in the refreshed access token; that
- * depends on "Assert Roles on Authentication" being enabled at the Zitadel
- * project level.
- */
-declare const ZITADEL_REFRESH_TOKEN_ALLOWED_SCOPE = "openid profile email";
-//#endregion
-//#region src/auth/bypass.d.ts
-type BypassStorage = Pick<Storage, 'getItem' | 'setItem'>;
-interface AuthBypassProfile {
-  sub: string;
-  email: string;
-  name: string;
-}
-interface SeedAuthBypassOptions {
-  /** The shared secret the API accepts as a Bearer token. Falsy → no-op. */
-  bypassSecret: string | null | undefined;
-  issuerUrl: string;
-  clientId: string;
-  /**
-   * MUST be the build-time production flag (e.g. `import.meta.env.PROD`).
-   * When `true` the seed is refused unconditionally — a leaked runtime env var
-   * cannot enable the bypass in a production build.
-   */
-  isProductionBuild: boolean;
-  /** Identity baked into the fake session. */
-  profile?: AuthBypassProfile;
-  /** Fake session lifetime. Default 86400 (24h). */
-  sessionTtlSeconds?: number;
-  storage?: BypassStorage;
-  /** Default `console.warn`. */
-  warn?: (message: string) => void;
-}
-/**
- * Dev/E2E auth bypass: seed storage with a fake oidc-client-ts user whose
- * `access_token` is the bypass secret, so the app considers the session
- * authenticated and the API client sends the secret as Bearer.
- *
- * Call from a plugin that runs before the OIDC plugin. Skips seeding when a
- * valid (non-expired) session already exists; overwrites corrupt entries.
- * Returns whether a session was seeded.
- */
-declare function seedAuthBypassSession(options: SeedAuthBypassOptions): boolean;
-//#endregion
-//#region src/auth/session.d.ts
-/** Default mapped shape of the authenticated user. */
-interface AuthSessionUser {
-  id: string;
-  email: string;
-  name: string | null;
-  picture: string | null;
-}
-interface AuthSessionCoreOptions<TUser> {
-  getUserManager: () => UserManager;
-  /** Map OIDC profile claims to the app's user shape. */
-  mapUser: (profile: UserProfile) => TUser;
-  /** Default `console.warn`. */
-  log?: (message: string, detail?: unknown) => void;
-}
-interface AuthSessionCore<TUser> {
-  user: Ref<TUser | null>;
-  initialized: Ref<boolean>;
-  loading: Ref<boolean>;
-  isAuthenticated: ComputedRef<boolean>;
-  /** Restore the session from storage, silently renewing an expired token. */
-  checkAuth: () => Promise<void>;
-  /** Start the signin redirect, carrying `returnUrl` as state. */
-  login: (returnUrl?: string) => Promise<void>;
-  /** Complete the signin redirect; returns the returnUrl state (default `/`). */
-  handleCallback: () => Promise<string>;
-  /** Clear the local session and redirect to the IdP's logout endpoint. */
-  logout: () => Promise<void>;
-}
-declare function defaultAuthUserMapper(profile: UserProfile): AuthSessionUser;
-/**
- * Reactive OIDC session state + actions — the setup body of an auth store.
- * Wrap it in the app's own store so naming and registration stay app-owned:
- *
- * ```ts
- * export const useAuthStore = defineStore('auth', () =>
- *   createAuthSessionCore({ getUserManager, mapUser: defaultAuthUserMapper }),
- * )
- * ```
- */
-declare function createAuthSessionCore<TUser = AuthSessionUser>(options: AuthSessionCoreOptions<TUser>): AuthSessionCore<TUser>;
-//#endregion
-//#region src/auth/guard.d.ts
-/** The route fields the guard needs — structurally satisfied by a Nuxt route. */
-interface GuardRoute {
-  path: string;
-  fullPath: string;
-}
-interface AuthGuardOptions<TRoute extends GuardRoute = GuardRoute> {
-  /**
-   * Ensure the session is restored and report whether the user is
-   * authenticated — typically `checkAuth()` once, then `isAuthenticated`.
-   */
-  ensureAuthenticated: () => Promise<boolean> | boolean;
-  /** Routes reachable without auth. Default: `/login` and `/auth/*`. */
-  isPublicRoute?: (to: TRoute) => boolean;
-  /** Build the login redirect target. Default `/login?redirect=<returnTo>`. */
-  loginRedirect?: (returnTo: string) => string;
-  /**
-   * Per-app policy hook that runs once the user is authenticated — tenant/org
-   * validation, role gates, acceptance gates. Return a path to redirect to,
-   * or nothing to let the navigation through.
-   */
-  afterAuthenticated?: (to: TRoute) => Promise<string | undefined | void> | string | undefined | void;
-}
-/**
- * Build the body of a global auth route-middleware. The returned handler
- * yields a redirect target path or `undefined` to allow navigation; the app's
- * middleware maps that onto its router:
- *
- * ```ts
- * export default defineNuxtRouteMiddleware(async (to) => {
- *   const target = await guard(to)
- *   if (target) return navigateTo(target)
- * })
- * ```
- */
-declare function createAuthGuard<TRoute extends GuardRoute = GuardRoute>(options: AuthGuardOptions<TRoute>): (to: TRoute) => Promise<string | undefined>;
-//#endregion
-//#region src/api/client.d.ts
-type AnyElysia = Elysia<any, any, any, any, any, any, any>;
-interface ResolveApiBaseUrlOptions {
-  /**
-   * The explicitly configured URL, first-match-wins — e.g.
-   * `__APP_CONFIG__.API_URL || runtimeConfig.public.apiUrl`. Falsy → fallback.
-   */
-  configuredUrl: string | null | undefined;
-  /** Build-time production flag (`import.meta.env.PROD`). */
-  isProductionBuild: boolean;
-  /** Dev fallback becomes `http://localhost:<port>`. */
-  devFallbackPort: number;
-  /** Production fallback origin. Default `window.location.origin`. */
-  origin?: string;
-}
-/**
- * Resolve the API base URL: configured value, else the page origin in
- * production builds (same-host ingress), else a localhost dev port.
- */
-declare function resolveApiBaseUrl(options: ResolveApiBaseUrlOptions): string;
-/**
- * Bearer-token provider backed by the OIDC session: resolves to the current
- * access token, or `null` when there is no non-expired session.
- */
-declare function createAccessTokenProvider(getUserManager: () => UserManager): () => Promise<string | null>;
-interface TreatyClientFactoryOptions {
-  /** Resolve (and memoize, if desired) the base URL at first client use. */
-  getBaseUrl: () => string;
-  /** Bearer token per request; `null` sends no Authorization header. */
-  getAccessToken: () => Promise<string | null>;
-  /**
-   * Eden Treaty's auto-Date parsing on responses. Default `false`: with the
-   * default `true`, any `YYYY-MM-DD` string in a response is silently
-   * converted to a `Date` object, which then JSON-serializes back as a full
-   * ISO datetime on the next request — breaking server-side "plain ISO date
-   * string" validation. Keep the wire contract string-typed unless the API
-   * genuinely round-trips Date objects.
-   */
-  parseDate?: boolean;
-  /** Extra Treaty config (fetcher, onRequest, …), applied last. */
-  treatyConfig?: Omit<Treaty.Config, 'headers' | 'parseDate'>;
-}
-/**
- * Lazily-created Eden Treaty client singleton with OIDC bearer injection.
- *
- * ```ts
- * const getClient = createTreatyClientFactory<App>({ getBaseUrl, getAccessToken })
- * export function useApi() {
- *   const client = getClient()
- *   return { api: client.api, client }
- * }
- * ```
- */
-declare function createTreatyClientFactory<App extends AnyElysia>(options: TreatyClientFactoryOptions): () => Treaty.Create<App>;
-//#endregion
+import { Component, ComputedRef, InjectionKey, Ref } from "vue";
 //#region src/org/orgStore.d.ts
 type OrgStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
 /** Result seam for the org fetch — mirrors an Eden Treaty `{ data, error }`. */
@@ -342,6 +47,16 @@ interface OrgStoreCore<TOrg> {
  */
 declare function createOrgStoreCore<TOrg>(options: OrgStoreCoreOptions<TOrg>): OrgStoreCore<TOrg>;
 //#endregion
+//#region src/runtimeConfig.d.ts
+/**
+ * Runtime-config lookup for SPAs deployed behind a static file server: an
+ * entrypoint script may define `window.__APP_CONFIG__` (values injected at
+ * deploy time), which takes precedence over the build-time fallback (e.g.
+ * Nuxt `runtimeConfig.public.*`).
+ */
+declare function resolveRuntimeConfigValue(appConfigKey: string, fallback: string): string;
+declare function resolveRuntimeConfigValue(appConfigKey: string, fallback?: string): string | undefined;
+//#endregion
 //#region src/composables/useConfirm.d.ts
 interface ConfirmOptions {
   title: string;
@@ -397,24 +112,64 @@ interface ApiErrorMessengerOptions {
   /** Default `console.error`. Pass `() => {}` to silence. */
   log?: (message: string, error: unknown) => void;
 }
-/**
- * Map API error bodies to user-facing i18n strings using a fixed key
- * convention the consumer's locale files fulfil:
- *
- * - `errors.<key>` — one entry per API error key (fallback: the raw
- *   server `message`, and `errors.internal_server_error` for non-API errors)
- * - `validation.fields.<path>` — display names for validated fields
- * - `validation.messages.<snake_cased_message>` — validation message texts
- *
- * Framework-free: pass `t`/`te` from your i18n instance (the app-side
- * composable is typically `const { t, te } = useI18n()` + this factory).
- * Eden Treaty error envelopes (`{ value }`) are unwrapped automatically.
- */
 declare function createApiErrorMessenger(options: ApiErrorMessengerOptions): {
   getErrorMessage: (error: unknown) => string;
   isValidationError: (error: unknown) => error is ValidationApiErrorLike;
 };
 //#endregion
+//#region src/composables/useHelpPanel.d.ts
+interface HelpPanelAction {
+  /** Unique key for this action within the tab */
+  key: string;
+  /** Display label */
+  label: string;
+  /** Icon name (e.g. i-lucide-circle-help) */
+  icon: string;
+  /** Raw Vue component to render in the panel */
+  component: Component;
+  /** Props to pass to the component (should be reactive) */
+  props: Record<string, unknown>;
+}
+interface HelpPanelRegistration {
+  actions: HelpPanelAction[];
+}
+interface HelpPanel {
+  /** Map of tab value -> registration */
+  registrations: Map<string, HelpPanelRegistration>;
+  /** Whether the panel is open */
+  isOpen: Ref<boolean>;
+  /** Currently active tab value */
+  activeTabValue: Ref<string>;
+  /** Actions for the currently active tab */
+  currentActions: ComputedRef<HelpPanelAction[]>;
+  /** Whether the active tab has any help actions */
+  hasActions: ComputedRef<boolean>;
+  /** Register help actions for a tab */
+  register(tabValue: string, actions: HelpPanelAction[]): void;
+  /** Unregister help actions for a tab */
+  unregister(tabValue: string): void;
+  /** Set the currently active tab */
+  setActiveTab(tabValue: string): void;
+  /** Toggle the panel open/closed */
+  toggle(): void;
+}
+declare const HELP_PANEL_KEY: InjectionKey<HelpPanel>;
+interface HelpPanelOptions {
+  /** localStorage key persisting the open state. Default `help-panel-open`. */
+  storageKey?: string;
+  /** Storage override (tests). Default `globalThis.localStorage`. */
+  storage?: Pick<Storage, 'getItem' | 'setItem'>;
+}
+/**
+ * Provide/inject registry for a per-tab contextual help panel: pages register
+ * help actions keyed by tab, `PageUtilityActions` renders the toggle, and a
+ * panel component renders `currentActions`. Open state persists to
+ * localStorage; switching to a tab without actions auto-closes the panel.
+ *
+ * Provide it per page: `provide(HELP_PANEL_KEY, useHelpPanel())`.
+ */
+declare function useHelpPanel(options?: HelpPanelOptions): HelpPanel;
+//#endregion
 //#region src/composables/useDirtyTracking.d.ts
 /**
  * Form change-detection over a reactive state object via JSON deep-compare:
@@ -450,4 +205,4 @@ declare function usePagination(options?: {
   resetPagination: () => void;
 };
 //#endregion
-export { type ApiErrorLike, type ApiErrorMessengerOptions, type AuthBypassProfile, type AuthGuardOptions, type AuthSessionCore, type AuthSessionCoreOptions, type AuthSessionUser, type ConfirmOptions, type FetchOrganizationsResult, type GuardRoute, type LoginRedirectorOptions, type OidcClientConfig, type OrgStoreCore, type OrgStoreCoreOptions, type ResolveApiBaseUrlOptions, type SeedAuthBypassOptions, type SessionLifecycleHandlers, type SessionNotice, type TreatyClientFactoryOptions, type UserManagerFactoryOptions, type ValidationApiErrorLike, ZITADEL_ORG_PROJECT_SCOPE, ZITADEL_REFRESH_TOKEN_ALLOWED_SCOPE, attachSessionLifecycleHandlers, createAccessTokenProvider, createApiErrorMessenger, createAuthGuard, createAuthSessionCore, createLoginRedirector, createOrgStoreCore, createTreatyClientFactory, createUserManagerFactory, defaultAuthUserMapper, isUnrecoverableRenewError, removeStaleOidcKeys, resolveApiBaseUrl, seedAuthBypassSession, useConfirm, useConfirmState, useDirtyTracking, usePagination };
+export { type ApiErrorLike, type ApiErrorMessengerOptions, type ConfirmOptions, type FetchOrganizationsResult, HELP_PANEL_KEY, type HelpPanel, type HelpPanelAction, type HelpPanelOptions, type HelpPanelRegistration, type OrgStoreCore, type OrgStoreCoreOptions, type ValidationApiErrorLike, createApiErrorMessenger, createOrgStoreCore, resolveRuntimeConfigValue, useConfirm, useConfirmState, useDirtyTracking, useHelpPanel, usePagination };