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

package/dist/utils/format.d.ts

@@ -28,6 +28,13 @@ export declare function formatPrice(price: number, currency?: string): string;
  * @returns Formatted bytes string
  */
 export declare function formatBytes(bytes: number, decimals?: number): string;
+/**
+ * Compact bytes formatter using the single-letter unit `'B'` (not
+ * `'Bytes'`). Used by upload-progress UIs where horizontal space is
+ * tight and the longer "Bytes" string wraps. Tops out at `TB`.
+ * @example formatBytesShort(0) → "0 B"; formatBytesShort(1536) → "1.5 KB"
+ */
+export declare function formatBytesShort(bytes: number): string;
 /**
  * Format large numbers to abbreviated form (K, M, B) with no decimal points
  * @param num - The number to format
@@ -37,8 +44,192 @@ export declare function formatLargeNumber(num: number): string;
 /**
  * Abbreviate large numbers for compact display.
  * 1 200 → 1.2K , 15 000 → 15K , 2 000 000 → 2M
- * Mirrors helper previously embedded in profile components.
  * @param n Number to format
  */
 export declare function formatAbbreviatedNumber(n: number): string;
+/**
+ * Two-letter uppercase initials from the FIRST + LAST word of a name.
+ * Used by avatar-style fallbacks (SquareAvatar, EntityImage) where
+ * "John Michael Doe" → "JD" reads better than "JM".
+ *
+ * Returns `''` for empty / whitespace-only input. Single-word names
+ * return a single uppercase letter. Pure — same input always produces
+ * the same output, no locale or timezone surface.
+ */
+export declare function getFirstLastInitials(name?: string | null): string;
+/**
+ * Two-letter uppercase initials from the FIRST + SECOND word of a name.
+ * Used as SquareAvatar / EntityImage / EntityAuthorCard fallback across
+ * admin and public pages in both the lib and the hub. Handles empty
+ * strings, all-whitespace input, and single-word names cleanly — always
+ * returns at least one character so the fallback slot is never empty.
+ *
+ * Single source of truth: every "first-letter of each word, uppercase,
+ * max 2 chars" computation across hub + lib MUST come through here.
+ */
+export declare function nameInitials(name: string | null | undefined, fallback?: string): string;
+/**
+ * Format seconds to MM:SS or HH:MM:SS format
+ * Used for media durations (podcasts, videos)
+ * Returns: "MM:SS" or "HH:MM:SS" if hours > 0
+ */
+export declare function formatDurationMMSS(seconds: number | null | undefined): string;
+/**
+ * Format seconds to compact human-readable duration
+ * Used for displaying duration in cards and headers
+ * Returns: "Xh Xm" or "X min"
+ */
+export declare function formatDurationCompact(seconds: number | null | undefined): string;
+/**
+ * Format time with optional timezone
+ * Used for webinar and event times
+ * Returns: "10:30 AM EST" or "10:30 AM"
+ */
+export declare function formatTimeWithTimezone(date: Date | string | null | undefined, timezone?: string | null): string;
+/**
+ * Calculate and format duration between two timestamps
+ * Used for webinar durations
+ * Returns: "1h 30m" or "45m"
+ */
+export declare function formatDurationFromRange(startAt: string | Date | null | undefined, endAt: string | Date | null | undefined): string;
+/**
+ * UTC-anchored date formatter — distinct from the local-rendering
+ * `formatDate` above. RAG mappers + audit-style consumers want UTC anchor
+ * so date-only strings (`'2024-08-15'`) don't drift across timezones, AND
+ * a `'N/A'` (or caller-supplied) fallback for missing values so the LLM
+ * never sees a blank.
+ *
+ * Accepts:
+ *   - ISO date or timestamp string (`'2024-08-15'` or `'2024-08-15T10:30:00Z'`)
+ *   - Numeric epoch milliseconds
+ *   - Numeric string (treated as epoch ms — Slack and GitHub timestamps
+ *     sometimes arrive that way)
+ *   - `null` / `undefined` / empty / unparseable → returns `options.fallback`
+ *
+ * Date-only strings (no `'T'`) get `T00:00:00Z` appended so they anchor to
+ * UTC midnight rather than midnight in the runtime's local timezone.
+ */
+export interface FormatDateUTCOptions {
+    /** Returned for null/undefined/empty/unparseable input. Defaults to 'N/A'. */
+    fallback?: string;
+    /** 'UTC' (default) or 'local' — switch off the UTC anchor when audit
+     *  stability matters less than local relevance (chat-card timestamps). */
+    timezone?: 'UTC' | 'local';
+}
+export declare function formatDateUTC(value: string | number | null | undefined, options?: FormatDateUTCOptions): string;
+/**
+ * Format a date string as `MM/DD/YYYY` for legal-document display
+ * (privacy policy, terms of service). Locale-stable: always en-US.
+ */
+export declare function formatLegalDate(dateInput: string): string;
+/**
+ * Format a currency value as `$1,234`. Returns `'N/A'` for null/undefined.
+ * USD-rounded (no cents). Used on KPI cards + investor pages.
+ */
+export declare function formatCurrency(value: number | null | undefined): string;
+/**
+ * Format a percent value as `12.50%`. Returns `'N/A'` for null/undefined.
+ */
+export declare function formatPercent(value: number | null | undefined): string;
+/**
+ * Whole-dollar price (no cents) — `$1,234`. Configurable currency code.
+ */
+export declare function formatWholeDollars(price: number, currency?: string): string;
+export type MetricFormat = 'number' | 'currency' | 'percentage' | 'months';
+/**
+ * Polarity determines whether an increase is good or bad.
+ * - 'positive': higher is better (revenue, users, MRR) → up = green, down = red
+ * - 'negative': higher is worse (burn rate, churn, CAC) → up = red, down = green
+ * - 'neutral':  no judgment (headcount, runway) → always gray
+ */
+export type TrendPolarity = 'positive' | 'negative' | 'neutral';
+/**
+ * Format a metric value with compact notation ($1.2M, 150K, 12 months).
+ */
+export declare function formatCompactMetric(value: number, format?: MetricFormat, options?: {
+    prefix?: string;
+    suffix?: string;
+}): string;
+/**
+ * Get ODS trend colors based on direction AND polarity. Single source
+ * of truth for trend coloring across hub + lib.
+ */
+export declare function getTrendColors(direction: 'up' | 'down' | 'neutral', polarity?: TrendPolarity): {
+    textClass: string;
+    badgeClass: string;
+};
+/**
+ * Format a date range as `Apr 20, 2026 — Jul 20, 2026`. Used on review
+ * cycle list/detail rows and summary headers.
+ *
+ * Accepts either full ISO timestamps or bare `YYYY-MM-DD` dates. Bare
+ * dates are interpreted in the viewer's LOCAL timezone — otherwise
+ * `"2026-04-20"` renders as `"Apr 19"` west of UTC. DB values for cycle
+ * period are stored as plain dates, so local-tz parsing is correct.
+ */
+export declare function formatDateRange(start: string | null | undefined, end: string | null | undefined): string;
+/**
+ * Format an ISO date string as `"Jan 5, 2025 at 10:30 AM"`. Used by
+ * admin podcast/webinar cards where the display needs both the short
+ * date AND wall-clock time in a single readable phrase.
+ *
+ * Uses `new Date(...).toLocale*` (NOT the TZ-safe split) because the
+ * source columns store full timestamps + the wall-clock half MUST
+ * render in the viewer's local timezone (a podcast scheduled "10:30 AM
+ * EST" should display "10:30 AM" for the Eastern admin, "7:30 AM" for
+ * the Pacific admin — viewer-local is the right semantics here, unlike
+ * date-only fields).
+ */
+export declare function formatDateTimeAt(dateString: string): string;
+/**
+ * Format a duration measured in MILLISECONDS as a compact human-readable
+ * string. Returns `"0ms"` for null/NaN/negative, then `Xms` → `X.Xs` →
+ * `X.Xm` as the input grows. Used by job-runs / orchestrator dashboards
+ * where elapsed milliseconds is the natural unit.
+ *
+ * Distinct from `formatDuration(seconds)` (verbose `"X hours Y minutes"`)
+ * and `formatDurationMMSS(seconds)` (media timecode `MM:SS`).
+ */
+export declare function formatDurationFromMs(ms: number | null | undefined): string;
+/**
+ * Format seconds to verbose human-readable duration: `"X seconds"`,
+ * `"X minutes"`, `"X hours Y minutes"`. Use this for human-readable
+ * spans; for media timecodes use `formatDurationMMSS`; for compact
+ * media labels use `formatDurationCompact`; for elapsed milliseconds
+ * use `formatDurationFromMs`.
+ */
+export declare function formatDuration(seconds: number): string;
+/**
+ * Format underscore-separated text into proper case.
+ *   `"self_hosted"` → `"Self Hosted"`
+ *   `"open_source"` → `"Open Source"`
+ */
+export declare function formatUnderscoreText(text: string): string;
+/**
+ * Strip HTML tags and decode common HTML entities from a string.
+ * Useful for cleaning API responses that contain HTML content.
+ *
+ * @example
+ * stripHtml('<p>Hello <strong>World</strong></p>') // "Hello World"
+ * stripHtml('Test &amp; Example') // "Test & Example"
+ */
+export declare function stripHtml(html: string): string;
+/**
+ * Display label for the openmsp `vendors.classification` enum.
+ * Falls back to proper-cased underscore split for values not in the
+ * curated mapping.
+ */
+export declare function formatClassification(classification: string): string;
+/**
+ * Display label for the openmsp `vendors.pricing_model` enum.
+ * Falls back to proper-cased underscore split for values not in the
+ * curated mapping.
+ */
+export declare function formatPricingModel(pricingModel: string): string;
+/**
+ * Format a bio/about text from the profiles table for display.
+ * Handles HTML content (e.g. `<p>` tags from rich text editors),
+ * plain text passthrough, and null/undefined values.
+ */
+export declare function formatBioText(aboutHtml: string | null | undefined, fallback?: string): string;
 //# sourceMappingURL=format.d.ts.map

package/dist/utils/format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/utils/format.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,IAAI,GAAG,MAAM,EACnB,OAAO,GAAE,IAAI,CAAC,qBAIb,GACA,MAAM,CAUR;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,SAAQ,GAAG,MAAM,CAKnE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAU/D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAwBrD;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAczD"}
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/utils/format.ts"],"names":[],"mappings":"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"}

package/dist/utils/image-proxy.d.ts

@@ -1,3 +1,68 @@
-export declare function getProxiedImageUrl(url: string): string;
-export declare function generateImageSizes(url: string): string;
+/**
+ * Pure image-proxy URL builder + helpers.
+ *
+ * Lib-side replacement for the hub's `lib/utils/image-proxy.ts`. The
+ * hub used to hardcode `/api/image-proxy` + an `openmsp.ai` skip-domain;
+ * this version takes BOTH as parameters so embedded apps (and other
+ * platforms that host the lib) can wire their own proxy prefix + skip
+ * list at the runtime layer.
+ *
+ * Pure function — no side effects, no env reads. Callers thread the
+ * proxy config through (typically from `ChatRuntime.endpoints.imageProxyUrlPrefix`).
+ */
+export type GetProxiedImageUrlOptions = {
+    /**
+     * URL prefix for the image proxy (`<prefix>?url=<encoded>`). When unset,
+     * `getProxiedImageUrl` returns the original URL unchanged — relative
+     * URLs always pass through. Hub default: `/api/image-proxy`.
+     */
+    proxyPrefix?: string;
+    /**
+     * Domains that should bypass the proxy (e.g. own-CDN hosts whose
+     * `Content-Type` is reliable and that already serve CORS-permitting
+     * headers). Matched as `imageUrl.includes(domain)` so subdomains
+     * inherit. Default: `[]`.
+     */
+    skipDomains?: string[];
+    /**
+     * Return the original `https://` URL so the browser loads it directly
+     * (no proxy). Use when upstream `Content-Type` breaks the proxy (common
+     * with SVG on some CDNs) or you want the origin to see the client
+     * request. HTTP stays proxied (mixed content / legacy).
+     */
+    directHttps?: boolean;
+};
+/**
+ * Resolve an external image URL through (or around) the image proxy.
+ *
+ * Resolution order:
+ *   1. `imageUrl` already contains `proxyPrefix` → return unchanged
+ *      (self-skip — prevents double-wrap).
+ *   2. `directHttps` set AND `imageUrl` starts with `https://` → return
+ *      unchanged.
+ *   3. `imageUrl` doesn't start with `http://` or `https://` → return
+ *      unchanged (relative URLs pass through).
+ *   4. `proxyPrefix` unset → return unchanged.
+ *   5. `skipDomains` matches the URL's host → return unchanged.
+ *   6. Else return `<proxyPrefix>?url=<encoded>`.
+ */
+export declare function getProxiedImageUrl(imageUrl: string | null, options?: GetProxiedImageUrlOptions): string | null;
+/**
+ * Heuristic: URL path looks like an SVG. Useful with `{ directHttps: true }`
+ * when only SVGs misbehave through the proxy; raster images can stay
+ * proxied if you prefer.
+ */
+export declare function urlPathLooksLikeSvg(imageUrl: string): boolean;
+/**
+ * Check if an image URL needs to be proxied. `proxyPrefix` is the same
+ * value passed to `getProxiedImageUrl` — used to short-circuit the
+ * self-skip case.
+ */
+export declare function shouldProxyImage(imageUrl: string | null, proxyPrefix?: string): boolean;
+/**
+ * Generate a responsive `sizes` attribute for `<img>` / `<Image>` tags.
+ * Pure utility — kept here for backwards-compatibility with the previous
+ * stub.
+ */
+export declare function generateImageSizes(_url: string): string;
 //# sourceMappingURL=image-proxy.d.ts.map

package/dist/utils/image-proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"image-proxy.d.ts","sourceRoot":"","sources":["../../src/utils/image-proxy.ts"],"names":[],"mappings":"AAAA,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGtD;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGtD"}
+{"version":3,"file":"image-proxy.d.ts","sourceRoot":"","sources":["../../src/utils/image-proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,MAAM,yBAAyB,GAAG;IACtC;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,OAAO,CAAC,EAAE,yBAAyB,GAClC,MAAM,GAAG,IAAI,CAsCf;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAM7D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAKT;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD"}