@octabits-io/nuxt-ui-kit 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 The Octabits Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# @octabits-io/nuxt-ui-kit
+
+Frontend kit for Nuxt/Vue admin SPAs. Ships **factory-style seams** — the app
+keeps thin plugin/store/middleware files and wires the kit into them; the kit
+never touches Nuxt APIs (`defineNuxtPlugin`, `navigateTo`, `useRuntimeConfig`)
+itself, so it has no Nuxt dependency, only `vue`.
+
+## What's inside
+
+- **OIDC session harness** (`oidc-client-ts` peer)
+  - `createUserManagerFactory({ getConfig, scope, … })` — lazy `UserManager`
+    singleton bound to `localStorage`
+  - `removeStaleOidcKeys`, `isUnrecoverableRenewError`
+  - `createLoginRedirector` — signin redirect carrying the current path as
+    returnUrl, with a `/login?redirect=` fallback
+  - `attachSessionLifecycleHandlers` — classifies silent-renew failures /
+    token expiry / back-channel signout into `notify` + `onSessionLost` +
+    login-redirect callbacks; copy and toasts stay in the app
+  - `ZITADEL_ORG_PROJECT_SCOPE` / `ZITADEL_REFRESH_TOKEN_ALLOWED_SCOPE`
+    presets (Zitadel restricts refresh-grant scopes — see the constant's docs)
+  - `seedAuthBypassSession` — dev/E2E bypass with an unconditional
+    production-build refusal (`isProductionBuild` is a required argument)
+- **Auth session store core** — `createAuthSessionCore` returns the setup body
+  (`user`/`checkAuth`/`login`/`handleCallback`/`logout`, silent-renew retry,
+  `id_token_hint` logout) for the app's own `defineStore('auth', …)`
+- **Route guard builder** — `createAuthGuard` returns a handler yielding a
+  redirect target or `undefined`; per-app policy (org validation, role gates)
+  goes in the `afterAuthenticated` hook
+- **Eden Treaty client factory** (`@elysiajs/eden` peer) —
+  `createTreatyClientFactory<App>` (lazy singleton, bearer injection,
+  `parseDate: false` by default to keep ISO-date strings string-typed on the
+  wire), plus `createAccessTokenProvider` and `resolveApiBaseUrl`
+- **Org store core** — `createOrgStoreCore<TOrg>` (granted orgs, slug-keyed
+  selection, persistence, lost-access revocation) for the app's own store
+- **API error → i18n** — `createApiErrorMessenger({ t, te })`: maps
+  `{ key, message }` bodies and validation errors to user-facing strings via
+  the `errors.*` / `validation.fields.*` / `validation.messages.*` key
+  convention; unwraps Eden `{ value }` envelopes
+- **Confirm dialog** — promise-based `useConfirm()` + singleton state, with a
+  `./components/ConfirmDialog.vue` renderer (`common.cancel`/`common.confirm`
+  i18n defaults, `zIndexClass` prop for stacking above slideovers)
+- **Generic primitives** — `useDirtyTracking` (deep-compare form dirty state),
+  `usePagination` (offset pagination with `queryParams`),
+  `./components/SubSidebar.vue` (responsive list/detail layout — desktop
+  column, mobile slideover, `selectionQueryKey` auto-close)
+- **`./zod`** (`zod` peer) — `setupZodLocaleSync`: keep Zod's built-in error
+  messages in the active UI language
+- **`./dates`** (`date-fns` peer) — `Period`/`calculateDays`/`shiftIso`,
+  `useDateRangeInput`, and `createDateFormatter({ getLocale })` (the engine of
+  an app-side `useDateFormat`), plus source-shipped `./components/DateInput.vue`,
+  `DateRangeInput.vue` (travel/booking end-date semantics, blocked dates via
+  props, injected `availabilityCheck`), and `PeriodDisplay.vue`
+- **`./ai`** — frontend AI-workflow engine: `useAiWorkflow` /
+  `useAiWorkflowGuard` (poll-driven state over injected transport),
+  `createAiProgressCore` (cross-page tracking + completion/applied signals —
+  the setup body of the app's progress store), `useAiCardState`,
+  `useActiveAiWorkflowProbe`, `createWorkflowRegistry`, and
+  `./components/AiResultReviewCard.vue`; dialog/float shells stay in the app
+  (thin views over this state, registry- and router-coupled)
+
+## Components ship as source
+
+`./components/*.vue` files are published as **`.vue` source** — the consumer's
+Vite compiles them. They use only explicit imports (`@nuxt/ui/components/*.vue`,
+`vue-i18n`, `vue-router`), so no auto-import configuration is required, and
+they import kit composables from the **package root (self-reference)** so
+module-scoped singleton state (the confirm dialog) is shared with feature
+code. Register them under your app's own names with one-line re-exports:
+
+```ts
+// app/components/AppSubSidebar.ts
+export { default } from '@octabits-io/nuxt-ui-kit/components/SubSidebar.vue'
+```
+
+## Wiring examples (Nuxt)
+
+### Auth + API client
+
+```ts
+// app/plugins/10.oidc.client.ts
+export const getUserManager = createUserManagerFactory({
+  getConfig: () => ({ issuerUrl, clientId }),           // runtime config lookup
+  scope: ZITADEL_ORG_PROJECT_SCOPE,
+  refreshTokenAllowedScope: ZITADEL_REFRESH_TOKEN_ALLOWED_SCOPE,
+})
+export default defineNuxtPlugin((nuxtApp) => {
+  attachSessionLifecycleHandlers(getUserManager(), {
+    redirectToLogin: createLoginRedirector({ getUserManager }),
+    onSessionLost: () => useAuthStore().$patch({ user: null }),
+    notify: (notice) => toast.add(/* map notice.kind to your copy */),
+  })
+})
+
+// app/composables/useApi.ts
+const getClient = createTreatyClientFactory<App>({
+  getBaseUrl: () => resolveApiBaseUrl({ configuredUrl, isProductionBuild: import.meta.env.PROD, devFallbackPort: 3002 }),
+  getAccessToken: createAccessTokenProvider(getUserManager),
+})
+
+// app/stores/auth.ts
+export const useAuthStore = defineStore('auth', () =>
+  createAuthSessionCore({ getUserManager, mapUser: defaultAuthUserMapper }))
+
+// app/middleware/auth.global.ts
+const guard = createAuthGuard({ ensureAuthenticated, afterAuthenticated: appPolicy })
+export default defineNuxtRouteMiddleware(async (to) => {
+  const target = await guard(to)
+  if (target) return navigateTo(target)
+})
+```
+
+### Errors, confirm, formatting
+
+```ts
+// app/composables/useApiError.ts — bind your i18n instance
+export function useApiError() {
+  const { t, te } = useI18n()
+  return createApiErrorMessenger({ t: key => t(key), te: key => te(key) })
+}
+
+// anywhere — the ConfirmDialog.vue renderer must be mounted once in a layout
+const { confirm } = useConfirm()
+if (await confirm({ title: t('owners.delete.title'), dangerous: true })) { /* … */ }
+
+// app/composables/useDateFormat.ts
+export function useDateFormat() {
+  const { locale } = useI18n()
+  return createDateFormatter({ getLocale: () => locale.value })
+}
+```
+
+### AI workflows
+
+```ts
+// app/stores/aiProgress.ts — transport injected, signals consumed by pages
+export const useAiProgressStore = defineStore('ai-progress', () =>
+  createAiProgressCore<AiDialogRequest>({
+    fetchWorkflowStatus: async (id) => {
+      const { data, error } = await api.ai.workflows({ id }).get()
+      return error || !data ? null : data
+    },
+  }))
+
+// a page — rehydrate on mount, refuse duplicate triggers
+const ai = useAiWorkflowGuard<MyOutput>({
+  checkFn: fetchLatestWorkflow,
+  pollFn: fetchLatestWorkflow,
+  onCompleted: (wf) => showReview(wf.output),
+})
+await ai.trigger(() => api.ai.workflows.post({ type: 'listing-fields' }))
+```

package/dist/ai/index.d.ts

@@ -0,0 +1,255 @@
+import { MaybeRef, MaybeRefOrGetter, Ref } from "vue";
+//#region src/ai/types.d.ts
+type AiWorkflowStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+type AiWorkflowStepStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
+interface AiWorkflowStepData {
+  id: number;
+  key: string;
+  type: string;
+  status: AiWorkflowStepStatus;
+  dependencies: string[];
+  input?: unknown | null;
+  output?: unknown | null;
+  error?: string | null;
+  startedAt?: string | null;
+  completedAt?: string | null;
+}
+interface AiWorkflowData<TOutput = unknown> {
+  id: number;
+  type: string;
+  status: AiWorkflowStatus;
+  input: unknown;
+  output: TOutput | null;
+  error: string | null;
+  entityRef: string | null;
+  totalSteps: number;
+  completedSteps: number;
+  failedSteps: number;
+  steps: AiWorkflowStepData[];
+  createdAt: string;
+  startedAt: string | null;
+  completedAt: string | null;
+  appliedAt: string | null;
+}
+declare function isTerminalStatus(status: AiWorkflowStatus): boolean;
+declare function isActiveStatus(status: AiWorkflowStatus): boolean;
+//#endregion
+//#region src/ai/useAiWorkflow.d.ts
+interface UseAiWorkflowOptions<TOutput> {
+  /** Polling interval in milliseconds (default: 2000) */
+  interval?: number;
+  /** Called when workflow completes successfully */
+  onCompleted?: (workflow: AiWorkflowData<TOutput>) => void;
+  /** Called when workflow fails */
+  onFailed?: (workflow: AiWorkflowData<TOutput>) => void;
+  /** Called when workflow is cancelled */
+  onCancelled?: (workflow: AiWorkflowData<TOutput>) => void;
+}
+type PollFn<TOutput> = () => Promise<AiWorkflowData<TOutput> | null>;
+/**
+ * Poll-driven AI-workflow state: `start(pollFn)` fetches immediately and then
+ * polls until the workflow reaches a terminal status, firing the matching
+ * callback. The poll function is injected — the engine is transport-agnostic.
+ */
+declare function useAiWorkflow<TOutput = unknown>(options?: UseAiWorkflowOptions<TOutput>): {
+  workflow: import("vue").ShallowRef<AiWorkflowData<TOutput> | null, AiWorkflowData<TOutput> | null>;
+  isLoading: import("vue").Ref<boolean, boolean>;
+  isPolling: import("vue").Ref<boolean, boolean>;
+  status: import("vue").ComputedRef<AiWorkflowStatus | null>;
+  progress: import("vue").ComputedRef<number>;
+  isCompleted: import("vue").ComputedRef<boolean>;
+  isFailed: import("vue").ComputedRef<boolean>;
+  isCancelled: import("vue").ComputedRef<boolean>;
+  isTerminal: import("vue").ComputedRef<boolean>;
+  isActive: import("vue").ComputedRef<boolean>;
+  output: import("vue").ComputedRef<TOutput | null>;
+  error: import("vue").ComputedRef<string | null>;
+  start: (pollFn: PollFn<TOutput>) => void;
+  stop: () => void;
+  cancel: (cancelFn: () => Promise<void>) => Promise<void>;
+  refresh: () => Promise<void>;
+  setWorkflow: (data: AiWorkflowData<TOutput>) => void;
+};
+type UseAiWorkflowReturn<TOutput> = ReturnType<typeof useAiWorkflow<TOutput>>;
+//#endregion
+//#region src/ai/useAiWorkflowGuard.d.ts
+interface UseAiWorkflowGuardOptions<TOutput> extends UseAiWorkflowOptions<TOutput> {
+  /** Check for existing active workflow on mount. Returns the workflow data or null. */
+  checkFn: () => Promise<AiWorkflowData<TOutput> | null>;
+  /** Poll function used for ongoing status checks (typically same endpoint as checkFn) */
+  pollFn: PollFn<TOutput>;
+}
+/**
+ * useAiWorkflow plus a mount-time re-hydration check (resume polling a
+ * workflow that is already running) and a `trigger` that refuses to start a
+ * duplicate while one is active. All transport is injected.
+ */
+declare function useAiWorkflowGuard<TOutput = unknown>(options: UseAiWorkflowGuardOptions<TOutput>): {
+  workflow: import("vue").ShallowRef<AiWorkflowData<TOutput> | null, AiWorkflowData<TOutput> | null>;
+  isLoading: import("vue").Ref<boolean, boolean>;
+  isPolling: import("vue").Ref<boolean, boolean>;
+  status: import("vue").ComputedRef<AiWorkflowStatus | null>;
+  progress: import("vue").ComputedRef<number>;
+  isCompleted: import("vue").ComputedRef<boolean>;
+  isFailed: import("vue").ComputedRef<boolean>;
+  isCancelled: import("vue").ComputedRef<boolean>;
+  isTerminal: import("vue").ComputedRef<boolean>;
+  isActive: import("vue").ComputedRef<boolean>;
+  output: import("vue").ComputedRef<TOutput | null>;
+  error: import("vue").ComputedRef<string | null>;
+  start: (pollFn: PollFn<TOutput>) => void;
+  stop: () => void;
+  cancel: (cancelFn: () => Promise<void>) => Promise<void>;
+  refresh: () => Promise<void>;
+  setWorkflow: (data: AiWorkflowData<TOutput>) => void;
+  isChecking: import("vue").Ref<boolean, boolean>;
+  trigger: (triggerFn: () => Promise<void>) => Promise<boolean>;
+};
+type UseAiWorkflowGuardReturn<TOutput> = ReturnType<typeof useAiWorkflowGuard<TOutput>>;
+//#endregion
+//#region src/ai/progressCore.d.ts
+interface TrackedWorkflow {
+  workflowId: number;
+  workflowType: string;
+  entityRef: string | null;
+  entityId?: number;
+  status: AiWorkflowStatus;
+  progress: number;
+  totalSteps: number;
+  completedSteps: number;
+  dismissed: boolean;
+}
+interface AiWorkflowStatusSnapshot {
+  status: AiWorkflowStatus;
+  totalSteps: number;
+  completedSteps: number;
+}
+interface AiProgressCoreOptions {
+  /** Fetch the current status of one workflow; `null` skips this cycle. */
+  fetchWorkflowStatus: (workflowId: number) => Promise<AiWorkflowStatusSnapshot | null>;
+  /** Poll cadence while any tracked workflow is active. Default 3000ms. */
+  intervalMs?: number;
+}
+/**
+ * Cross-page AI-workflow progress tracking — the setup body of an app's
+ * progress store (`defineStore('ai-progress', () => createAiProgressCore(…))`).
+ * Tracks triggered workflows, polls the active ones through the injected
+ * fetch, and exposes `completionSignal` / `appliedSignal` counters pages watch
+ * to refresh their data. The dialog-request channel is generic over the app's
+ * request shape (typically `{ definition, entityId?, entityRef?, workflowId? }`).
+ */
+declare function createAiProgressCore<TDialogRequest>(options: AiProgressCoreOptions): {
+  trackedWorkflows: Ref<{
+    workflowId: number;
+    workflowType: string;
+    entityRef: string | null;
+    entityId?: number;
+    status: AiWorkflowStatus;
+    progress: number;
+    totalSteps: number;
+    completedSteps: number;
+    dismissed: boolean;
+  }[], TrackedWorkflow[] | {
+    workflowId: number;
+    workflowType: string;
+    entityRef: string | null;
+    entityId?: number;
+    status: AiWorkflowStatus;
+    progress: number;
+    totalSteps: number;
+    completedSteps: number;
+    dismissed: boolean;
+  }[]>;
+  activeWorkflows: import("vue").ComputedRef<{
+    workflowId: number;
+    workflowType: string;
+    entityRef: string | null;
+    entityId?: number;
+    status: AiWorkflowStatus;
+    progress: number;
+    totalSteps: number;
+    completedSteps: number;
+    dismissed: boolean;
+  }[]>;
+  hasActive: import("vue").ComputedRef<boolean>;
+  completionSignal: Ref<number, number>;
+  appliedSignal: Ref<number, number>;
+  dialogRequest: Ref<TDialogRequest | null, TDialogRequest | null>;
+  track: (workflowId: number, workflowType: string, entityRef: string | null, entityId?: number) => void;
+  dismiss: (workflowId: number) => void;
+  markApplied: (workflowId: number) => void;
+  untrack: (workflowId: number) => void;
+  getByEntityRef: (entityRef: string) => TrackedWorkflow | undefined;
+  openDialog: (request: TDialogRequest) => void;
+  closeDialog: () => void;
+  pollActive: () => Promise<void>;
+  reset: () => void;
+};
+type AiProgressCore<TDialogRequest> = ReturnType<typeof createAiProgressCore<TDialogRequest>>;
+//#endregion
+//#region src/ai/useAiCardState.d.ts
+/** The slice of the progress store the card state machine needs. */
+interface AiProgressLike {
+  getByEntityRef: (entityRef: string) => TrackedWorkflow | undefined;
+  dismiss: (workflowId: number) => void;
+}
+/**
+ * Shared state machine for AI trigger/suggestion cards. Derives the card
+ * phase from the workflow tracked in the (injected) progress store for the
+ * given entityRef.
+ */
+declare function useAiCardState(store: AiProgressLike, entityRef: MaybeRefOrGetter<string>, hasActiveWorkflow?: MaybeRefOrGetter<boolean | undefined>): {
+  trackedWorkflow: import("vue").ComputedRef<TrackedWorkflow | undefined>;
+  cardState: import("vue").ComputedRef<"active" | "failed" | "idle">;
+  failedWorkflow: import("vue").ComputedRef<TrackedWorkflow | null>;
+  dismissFailure: () => void;
+};
+//#endregion
+//#region src/ai/useActiveAiWorkflowProbe.d.ts
+interface ActiveAiWorkflowProbeOptions {
+  /** The entity the probe watches; `undefined` disables checking. */
+  entityRef: MaybeRef<string | undefined>;
+  /** Report whether an active workflow exists for the entity; `null` = unknown (keep last). */
+  fetchHasActive: (entityRef: string) => Promise<boolean | null>;
+  /** Poll cadence while a workflow is active. Default 3000ms. */
+  intervalMs?: number;
+}
+/**
+ * "Is something already running for this entity?" probe: checks on mount and
+ * whenever the entity changes, then polls while active so trigger buttons can
+ * disable themselves. Transport is injected.
+ */
+declare function useActiveAiWorkflowProbe(options: ActiveAiWorkflowProbeOptions): {
+  hasActive: import("vue").Ref<boolean, boolean>;
+  isChecking: import("vue").Ref<boolean, boolean>;
+  refresh: () => Promise<void>;
+};
+//#endregion
+//#region src/ai/registry.d.ts
+/**
+ * Typed workflow-type registry — the app owns its definition shape (trigger
+ * API context, dynamic components, label keys); the kit owns registration and
+ * label lookup.
+ */
+interface WorkflowRegistryOptions {
+  /**
+   * Label-key fallbacks for types that have no registered definition
+   * (e.g. usage-only rows like embedding jobs).
+   */
+  extraLabelKeys?: Record<string, string>;
+}
+declare function createWorkflowRegistry<TDefinition extends {
+  type: string;
+  labelKey: string;
+}>(options?: WorkflowRegistryOptions): {
+  register: (definition: TDefinition) => void;
+  get: (type: string) => TDefinition | undefined;
+  getAll: () => TDefinition[];
+  getLabel: (type: string, t: (key: string) => string) => string;
+};
+type WorkflowRegistry<TDefinition extends {
+  type: string;
+  labelKey: string;
+}> = ReturnType<typeof createWorkflowRegistry<TDefinition>>;
+//#endregion
+export { type ActiveAiWorkflowProbeOptions, type AiProgressCore, type AiProgressCoreOptions, type AiProgressLike, type AiWorkflowData, type AiWorkflowStatus, type AiWorkflowStatusSnapshot, type AiWorkflowStepData, type AiWorkflowStepStatus, type PollFn, type TrackedWorkflow, type UseAiWorkflowGuardOptions, type UseAiWorkflowGuardReturn, type UseAiWorkflowOptions, type UseAiWorkflowReturn, type WorkflowRegistry, type WorkflowRegistryOptions, createAiProgressCore, createWorkflowRegistry, isActiveStatus, isTerminalStatus, useActiveAiWorkflowProbe, useAiCardState, useAiWorkflow, useAiWorkflowGuard };