@flamingo-stack/openframe-frontend-core 0.0.204 → 0.0.205

package/src/hooks/state/use-query-params.ts

@@ -19,7 +19,7 @@
 'use client'
 
 import { useEffect, useState, useMemo, useCallback } from 'react'
-import { useRouter, useSearchParams } from 'next/navigation'
+import { useRouter, useSearchParams } from '../../embed-shims/next-navigation'
 import { DocumentNode } from 'graphql'
 
 import { extractVariablesFromQuery } from './graphql-parser'

package/src/hooks/use-access-code-integration.ts

@@ -0,0 +1,107 @@
+'use client'
+
+/**
+ * Access Code Integration Hook
+ *
+ * React-side wrapper around the pure `access-code-client` utilities.
+ * Lives in `hooks/` (client bundle) so the `createContext()` call in
+ * `endpoints-runtime-context` doesn't get pulled into the server-safe
+ * `utils/index` bundle.
+ *
+ * The pure standalone functions (`validateAccessCode`,
+ * `consumeAccessCode`, `validateAndConsumeAccessCode`) remain importable
+ * from `@flamingo-stack/openframe-frontend-core/utils` — they take the
+ * endpoints object as an argument. This hook binds those endpoints from
+ * `EndpointsRuntimeContext` so React callers don't have to plumb URLs.
+ */
+
+import React from 'react'
+
+import { useRequiredEndpointsRuntime } from '../contexts/endpoints-runtime-context'
+import {
+  validateAccessCode,
+  consumeAccessCode,
+  validateAndConsumeAccessCode,
+} from '../utils/access-code-client'
+
+/**
+ * Resolves access-code endpoints from `EndpointsRuntimeContext` (throws
+ * if no provider is mounted) and exposes loading-state-aware wrappers
+ * around the standalone helpers in `utils/access-code-client`.
+ *
+ * @returns the following fields. The `validate` / `consume` /
+ *   `validateAndConsume` functions and the returned object identity are
+ *   NOT memoized — they're re-created each render. Wrap with
+ *   `useCallback` / `useMemo` at the call site if downstream effect
+ *   dep arrays depend on stable identities.
+ *   - `validate(email, code)`: validates only.
+ *   - `consume(email, code)`: consumes only.
+ *   - `validateAndConsume(email, code)`: one-step validate-then-consume.
+ *   - `isValidating: boolean`: a validate call is in flight.
+ *   - `isConsuming: boolean`: a consume call is in flight.
+ *   - `isProcessing: boolean`: convenience — `isValidating || isConsuming`.
+ *     Use this for a single "in-flight" indicator on UI affordances that
+ *     should disable during both phases.
+ *
+ * @example
+ * const { validate, consume, isProcessing } = useAccessCodeIntegration();
+ *
+ * const handleRegistration = async (formData) => {
+ *   const validation = await validate(formData.email, formData.accessCode);
+ *   if (!validation.valid) {
+ *     setError(validation.message);
+ *     return;
+ *   }
+ *
+ *   // Process registration...
+ *   const registrationResult = await registerUser(formData);
+ *
+ *   if (registrationResult.success) {
+ *     await consume(formData.email, formData.accessCode);
+ *   }
+ * };
+ */
+export function useAccessCodeIntegration() {
+  const runtime = useRequiredEndpointsRuntime()
+  const endpoints = runtime.accessCode
+  const [isValidating, setIsValidating] = React.useState(false)
+  const [isConsuming, setIsConsuming] = React.useState(false)
+
+  const validate = async (email: string, code: string) => {
+    setIsValidating(true)
+    try {
+      return await validateAccessCode(email, code, endpoints)
+    } finally {
+      setIsValidating(false)
+    }
+  }
+
+  const consume = async (email: string, code: string) => {
+    setIsConsuming(true)
+    try {
+      return await consumeAccessCode(email, code, endpoints)
+    } finally {
+      setIsConsuming(false)
+    }
+  }
+
+  const validateAndConsume = async (email: string, code: string) => {
+    setIsValidating(true)
+    setIsConsuming(true)
+    try {
+      return await validateAndConsumeAccessCode(email, code, endpoints)
+    } finally {
+      setIsValidating(false)
+      setIsConsuming(false)
+    }
+  }
+
+  return {
+    validate,
+    consume,
+    validateAndConsume,
+    isValidating,
+    isConsuming,
+    isProcessing: isValidating || isConsuming,
+  }
+}

package/src/hooks/use-contact-submission.ts

@@ -1,6 +1,7 @@
 import { useState, useCallback, useEffect } from 'react';
 import { useToast } from "./use-toast";
-import { useRouter } from 'next/navigation';
+import { useRouter } from '../embed-shims/next-navigation';
+import { useRequiredEndpointsRuntime } from '../contexts/endpoints-runtime-context';
 
 interface ContactSubmissionOptions {
   userId?: string;
@@ -44,6 +45,9 @@ export function useContactSubmission(options: ContactSubmissionOptions = {}) {
   const { userId, successRedirectUrl, successToastMessage, onSuccess } = options;
   const { toast } = useToast();
   const router = useRouter();
+  // Endpoint URL injected via context — hub provides hub default, embedded
+  // app provides its proxied path. Throws if no provider is mounted.
+  const { contactUrl } = useRequiredEndpointsRuntime();
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [isSuccess, setIsSuccess] = useState(false);
 
@@ -53,7 +57,7 @@ export function useContactSubmission(options: ContactSubmissionOptions = {}) {
     setIsSubmitting(true);
 
     try {
-      const response = await fetch('/api/contact', {
+      const response = await fetch(contactUrl, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ 
@@ -90,7 +94,7 @@ export function useContactSubmission(options: ContactSubmissionOptions = {}) {
     } finally {
       setIsSubmitting(false);
     }
-  }, [isSubmitting, toast, userId, successToastMessage]);
+  }, [isSubmitting, toast, userId, successToastMessage, contactUrl]);
 
   // Handle redirect after success
   useEffect(() => {

package/src/hooks/use-og-placeholder.ts

@@ -0,0 +1,45 @@
+'use client'
+
+import { useMemo } from 'react'
+
+/**
+ * Hook that generates a branded placeholder image URL using the
+ * host's `/api/og-placeholder` server-side image generator (or any
+ * builder the caller supplies).
+ *
+ * THIS HOOK IS A THIN CLIENT-SIDE WRAPPER. The hub-side wrapper
+ * (`hooks/use-og-placeholder.ts` in multi-platform-hub) injects its
+ * canonical `buildOgPlaceholderUrl` from `lib/utils/entity-image.ts`.
+ * The lib version takes the builder as an argument so the lib has no
+ * hub dependency.
+ *
+ * @param buildUrl - Function that builds the placeholder URL from a
+ *                   title + options object (`{ site?, aspect? }`).
+ *                   Hub passes `buildOgPlaceholderUrl` from
+ *                   `lib/utils/entity-image.ts`. Embedded apps can
+ *                   wire any equivalent that hits their own placeholder
+ *                   route.
+ * @param title    - Text to display on the placeholder
+ * @param siteName - Site name shown below the title (optional —
+ *                   defaults to empty)
+ * @param enabled  - Whether to generate the URL (default: true)
+ * @param aspect   - `'wide'` (1200×630 social-card; default) or `'square'`
+ *                   (1024×1024 — used by compact chat-inline card slots
+ *                   so `object-cover` doesn't crop the title off).
+ * @returns Placeholder image URL or null if disabled / no title
+ */
+export function useOgPlaceholder(
+  buildUrl: (title: string, options: { site?: string; aspect?: 'wide' | 'square' }) => string,
+  title: string | undefined | null,
+  siteName: string = '',
+  enabled: boolean = true,
+  aspect: 'wide' | 'square' = 'wide',
+): string | null {
+  return useMemo(() => {
+    if (!enabled || !title) return null
+    const options: { site?: string; aspect?: 'wide' | 'square' } = {}
+    if (siteName) options.site = siteName
+    if (aspect === 'square') options.aspect = 'square'
+    return buildUrl(title, options)
+  }, [buildUrl, title, siteName, enabled, aspect])
+}

package/src/stories/OnboardingStepCard.stories.tsx

@@ -0,0 +1,140 @@
+import type { Meta, StoryObj } from '@storybook/nextjs-vite'
+import { OnboardingStepCard } from '../components/shared/onboarding/onboarding-step-card'
+import { UserPlusIcon } from '../components/icons-v2-generated/users/user-plus-icon'
+
+const baseStep = {
+  id: 'invite-users',
+  title: 'Company & Team',
+  description: 'Invite team members and set up roles',
+  actionIcon: (color?: string) => <UserPlusIcon color={color} size={20} />,
+  actionText: 'Invite Users',
+  completedText: 'Manage Users',
+  onAction: () => console.log('action'),
+  onSkip: () => console.log('skip'),
+}
+
+const meta = {
+  title: 'Shared/OnboardingStepCard',
+  component: OnboardingStepCard,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'A single row in the Get Started onboarding list. Renders title + description on the left and state-dependent controls on the right (Skip / Action, Completed badge + Manage, Skipped badge, or loading skeleton). The card itself has no click action — only the inner buttons are interactive — so it has no hover state.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof OnboardingStepCard>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/**
+ * Pending step — shows Skip Step + the primary action button.
+ */
+export const Default: Story = {
+  args: {
+    step: baseStep,
+    isCompleted: false,
+    isSkipped: false,
+    isCheckingCompletion: false,
+    onAction: () => console.log('action'),
+    onSkip: () => console.log('skip'),
+  },
+}
+
+/**
+ * Completed step — shows the success badge and a "Manage" button.
+ */
+export const Completed: Story = {
+  args: {
+    ...Default.args,
+    isCompleted: true,
+  },
+}
+
+/**
+ * Skipped step — shows only the SKIPPED badge.
+ */
+export const Skipped: Story = {
+  args: {
+    ...Default.args,
+    isSkipped: true,
+  },
+}
+
+/**
+ * Loading state while completion status is being checked.
+ */
+export const CheckingCompletion: Story = {
+  args: {
+    ...Default.args,
+    isCheckingCompletion: true,
+  },
+}
+
+/**
+ * Full list rendered the way it appears on the Get Started page.
+ * Use this story to verify that hovering any row does NOT change its
+ * border or background — only the inner buttons should react.
+ */
+export const List: Story = {
+  args: Default.args,
+  render: () => {
+    const steps = [
+      {
+        ...baseStep,
+        id: 'orgs',
+        title: 'Organizations Setup',
+        description: 'Create and configure your organizational structure',
+        completed: true,
+      },
+      {
+        ...baseStep,
+        id: 'devices',
+        title: 'Device Management',
+        description: 'Connect and monitor your fleet of devices',
+        completed: true,
+      },
+      {
+        ...baseStep,
+        id: 'team',
+        title: 'Company & Team',
+        description: 'Invite team members and set up roles',
+        completed: false,
+      },
+      {
+        ...baseStep,
+        id: 'sso',
+        title: 'SSO Configuration',
+        description: 'Link Microsoft 365, Google Workspace, and other identity providers',
+        completed: false,
+      },
+      {
+        ...baseStep,
+        id: 'kb',
+        title: 'Knowledge Base',
+        description: 'Access documentation and learning resources',
+        completed: false,
+      },
+    ]
+
+    return (
+      <div className="flex flex-col gap-3">
+        {steps.map((s) => (
+          <OnboardingStepCard
+            key={s.id}
+            step={s}
+            isCompleted={s.completed}
+            isSkipped={false}
+            isCheckingCompletion={false}
+            onAction={() => console.log('action', s.id)}
+            onSkip={() => console.log('skip', s.id)}
+          />
+        ))}
+      </div>
+    )
+  },
+}

package/src/styles/chat-animations.css

@@ -0,0 +1,65 @@
+/* =============================================================================
+ * Chat Panel (Mingo AI) — open/close motion
+ *
+ * Duration & easing follow Material 3 motion tokens + Nielsen Norman Group's
+ * 200–300 ms panel guidance:
+ *   - enter: 250 ms with emphasized-decelerate (settle into place)
+ *   - exit:  200 ms with emphasized-accelerate  (snap away)
+ * Only transform + opacity are animated so frames stay on the GPU compositor.
+ *
+ * On <md viewports the panel is a bottom sheet (slides up); on md+ it's a
+ * right side panel (slides in from the right edge). One keyframe set per axis.
+ *
+ * prefers-reduced-motion: cross-fade replaces all slide motion (vestibular-safe
+ * per WCAG 2.3.3 / MDN guidance) — the panel still animates, just without
+ * positional movement.
+ * ============================================================================= */
+
+@keyframes mingo-chat-overlay-in {
+  from { opacity: 0; }
+  to   { opacity: 1; }
+}
+@keyframes mingo-chat-overlay-out {
+  from { opacity: 1; }
+  to   { opacity: 0; }
+}
+
+@keyframes mingo-chat-slide-in-right {
+  from { opacity: 0; transform: translate3d(100%, 0, 0); }
+  to   { opacity: 1; transform: translate3d(0, 0, 0); }
+}
+@keyframes mingo-chat-slide-out-right {
+  from { opacity: 1; transform: translate3d(0, 0, 0); }
+  to   { opacity: 0; transform: translate3d(100%, 0, 0); }
+}
+
+@keyframes mingo-chat-slide-in-bottom {
+  from { opacity: 0; transform: translate3d(0, 100%, 0); }
+  to   { opacity: 1; transform: translate3d(0, 0, 0); }
+}
+@keyframes mingo-chat-slide-out-bottom {
+  from { opacity: 1; transform: translate3d(0, 0, 0); }
+  to   { opacity: 0; transform: translate3d(0, 100%, 0); }
+}
+
+@keyframes mingo-chat-fade-in {
+  from { opacity: 0; }
+  to   { opacity: 1; }
+}
+@keyframes mingo-chat-fade-out {
+  from { opacity: 1; }
+  to   { opacity: 0; }
+}
+
+.mingo-chat-overlay[data-state="open"]  { animation: mingo-chat-overlay-in  200ms cubic-bezier(0.05, 0.7, 0.1, 1) both; }
+.mingo-chat-overlay[data-state="closed"] { animation: mingo-chat-overlay-out 150ms cubic-bezier(0.3, 0, 0.8, 0.15) both; }
+
+/* Mobile: bottom-sheet motion */
+.mingo-chat-content[data-state="open"]   { animation: mingo-chat-slide-in-bottom  250ms cubic-bezier(0.05, 0.7, 0.1, 1) both; }
+.mingo-chat-content[data-state="closed"] { animation: mingo-chat-slide-out-bottom 200ms cubic-bezier(0.3, 0, 0.8, 0.15) both; }
+
+/* Desktop (>=768px): side-panel motion */
+@media (min-width: 768px) {
+  .mingo-chat-content[data-state="open"]   { animation-name: mingo-chat-slide-in-right; }
+  .mingo-chat-content[data-state="closed"] { animation-name: mingo-chat-slide-out-right; }
+}

package/src/styles/index.css

@@ -4,6 +4,7 @@
 @import "./ods-interaction-states.css";
 @import "./ods-responsive-tokens.css";
 @import "./app-globals.css";
+@import "./chat-animations.css";
 
 /* Vendor/library style overrides */
 @import "./vendor-react-easy-crop.css";

package/src/utils/access-code-client.ts

@@ -1,17 +1,32 @@
 /**
- * Access Code Client Utilities
+ * Access Code Client Utilities — pure standalone functions.
  *
- * Simple client-side utilities for integrating access code validation
- * and consumption into registration forms.
+ * Endpoint paths are NOT hardcoded — every function takes an
+ * `endpoints` argument. The React-side wrapper that binds them from
+ * `EndpointsRuntimeContext` lives separately at
+ * `hooks/use-access-code-integration.ts` (`useAccessCodeIntegration`).
+ *
+ * Keep this file **free of React imports** — it lives in the
+ * server-safe `utils/index` tsup bundle. Any module-top-level call
+ * into `createContext()` (which the runtime context file does) would
+ * be pulled into the server bundle and crash SSR with
+ * `createContext is not a function`.
  */
 
-import React from 'react';
 import {
   AccessCodeValidation,
   AccessCodeValidationResponse,
   AccessCodeConsumptionResponse
 } from '../types/access-code-cohorts';
 
+/** Endpoints required by the standalone client utilities. The
+ *  `useAccessCodeIntegration` hook (in `hooks/`) resolves these from
+ *  `EndpointsRuntimeContext.accessCode` automatically. */
+export interface AccessCodeEndpoints {
+  validateUrl: string
+  consumeUrl: string
+}
+
 /**
  * Validate an access code for a given email
  *
@@ -31,10 +46,11 @@ import {
  */
 export async function validateAccessCode(
   email: string,
-  code: string
+  code: string,
+  endpoints: AccessCodeEndpoints,
 ): Promise<AccessCodeValidationResponse> {
   try {
-    const response = await fetch('/api/validate-access-code', {
+    const response = await fetch(endpoints.validateUrl, {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
@@ -77,10 +93,11 @@ export async function validateAccessCode(
  */
 export async function consumeAccessCode(
   email: string,
-  code: string
+  code: string,
+  endpoints: AccessCodeEndpoints,
 ): Promise<AccessCodeConsumptionResponse> {
   try {
-    const response = await fetch('/api/consume-access-code', {
+    const response = await fetch(endpoints.consumeUrl, {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
@@ -125,17 +142,18 @@ export async function consumeAccessCode(
  */
 export async function validateAndConsumeAccessCode(
   email: string,
-  code: string
+  code: string,
+  endpoints: AccessCodeEndpoints,
 ): Promise<AccessCodeValidationResponse & { consumed?: boolean }> {
   // First validate
-  const validation = await validateAccessCode(email, code);
+  const validation = await validateAccessCode(email, code, endpoints);
 
   if (!validation.valid) {
     return validation;
   }
 
   // If valid, consume the code
-  const consumption = await consumeAccessCode(email, code);
+  const consumption = await consumeAccessCode(email, code, endpoints);
 
   return {
     ...validation,
@@ -146,67 +164,6 @@ export async function validateAndConsumeAccessCode(
   };
 }
 
-/**
- * Access Code Integration Hook (for React components)
- *
- * @example
- * const { validate, consume, isValidating, isConsuming } = useAccessCodeIntegration();
- *
- * const handleRegistration = async (formData) => {
- *   const validation = await validate(formData.email, formData.accessCode);
- *   if (!validation.valid) {
- *     setError(validation.message);
- *     return;
- *   }
- *
- *   // Process registration...
- *   const registrationResult = await registerUser(formData);
- *
- *   if (registrationResult.success) {
- *     await consume(formData.email, formData.accessCode);
- *   }
- * };
- */
-export function useAccessCodeIntegration() {
-  const [isValidating, setIsValidating] = React.useState(false);
-  const [isConsuming, setIsConsuming] = React.useState(false);
-
-  const validate = async (email: string, code: string) => {
-    setIsValidating(true);
-    try {
-      return await validateAccessCode(email, code);
-    } finally {
-      setIsValidating(false);
-    }
-  };
-
-  const consume = async (email: string, code: string) => {
-    setIsConsuming(true);
-    try {
-      return await consumeAccessCode(email, code);
-    } finally {
-      setIsConsuming(false);
-    }
-  };
-
-  const validateAndConsume = async (email: string, code: string) => {
-    setIsValidating(true);
-    setIsConsuming(true);
-    try {
-      return await validateAndConsumeAccessCode(email, code);
-    } finally {
-      setIsValidating(false);
-      setIsConsuming(false);
-    }
-  };
-
-  return {
-    validate,
-    consume,
-    validateAndConsume,
-    isValidating,
-    isConsuming,
-    isProcessing: isValidating || isConsuming,
-  };
-}
-
+// `useAccessCodeIntegration` (the React-side wrapper) lives in
+// `hooks/use-access-code-integration.ts`. It binds the endpoints from
+// `EndpointsRuntimeContext` so React callers don't have to plumb URLs.

package/src/utils/cn.ts

@@ -16,71 +16,6 @@ export function cn(...inputs: ClassValue[]) {
   return twMerge(clsx(inputs))
 }
 
-/**
- * Format a date to a human-readable string
- * @param date - The date to format (Date object or ISO string)
- * @param options - Formatting options
- * @returns Formatted date string
- */
-export function formatDate(
-  date: Date | string,
-  options: Intl.DateTimeFormatOptions = {
-    year: "numeric",
-    month: "long",
-    day: "numeric",
-  },
-): string {
-  const dateObj = typeof date === "string" ? new Date(date) : date
-  
-  // Check if the date is valid
-  if (isNaN(dateObj.getTime())) {
-    console.warn("Invalid date provided to formatDate:", date)
-    return "Invalid Date"
-  }
-  
-  return dateObj.toLocaleDateString("en-US", options)
-}
-
-/**
- * Format a number with thousands separators
- * @param num - The number to format
- * @returns Formatted number string
- */
-export function formatNumber(num: number): string {
-  return num.toLocaleString()
-}
-
-/**
- * Format a price with currency symbol
- * @param price - The price to format
- * @param currency - The currency code
- * @returns Formatted price string
- */
-export function formatPrice(price: number, currency = "USD"): string {
-  return new Intl.NumberFormat("en-US", {
-    style: "currency",
-    currency,
-  }).format(price)
-}
-
-/**
- * Format bytes to a human-readable string (KB, MB, GB, etc.)
- * @param bytes - The number of bytes
- * @param decimals - Number of decimal places
- * @returns Formatted bytes string
- */
-export function formatBytes(bytes: number, decimals = 2): string {
-  if (bytes === 0) return "0 Bytes"
-
-  const k = 1024
-  const dm = decimals < 0 ? 0 : decimals
-  const sizes = ["Bytes", "KB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB"]
-
-  const i = Math.floor(Math.log(bytes) / Math.log(k))
-
-  return Number.parseFloat((bytes / Math.pow(k, i)).toFixed(dm)) + " " + sizes[i]
-}
-
 /**
  * Platform URL mappings for production (with environment variable overrides)
  */