@ngbplatform/ui 1.3.0

package/src/ngb/utils/dateValues.ts

@@ -0,0 +1,107 @@
+export type YearMonthParts = {
+  year: number
+  month: number
+}
+
+const YEAR_MONTH_RE = /^(\d{4})-(\d{2})$/
+const DATE_ONLY_RE = /^(\d{4})-(\d{2})-(\d{2})$/
+
+export function parseMonthValue(value: string | null | undefined): YearMonthParts | null {
+  const normalized = String(value ?? '').trim()
+  const match = YEAR_MONTH_RE.exec(normalized)
+  if (!match) return null
+
+  const year = Number(match[1])
+  const month = Number(match[2])
+  if (!Number.isInteger(year) || month < 1 || month > 12) return null
+
+  return { year, month }
+}
+
+export function normalizeMonthValue(value: unknown): string | null {
+  const parsed = parseMonthValue(String(value ?? '').trim())
+  return parsed ? toMonthValue(parsed.year, parsed.month) : null
+}
+
+export function toMonthValue(year: number, month: number): string {
+  return `${year}-${String(month).padStart(2, '0')}`
+}
+
+export function currentMonthValue(now = new Date()): string {
+  return toMonthValue(now.getFullYear(), now.getMonth() + 1)
+}
+
+export function monthValueYear(value: string | null | undefined): number | null {
+  return parseMonthValue(value)?.year ?? null
+}
+
+export function shiftMonthValue(value: string | null | undefined, offset: number): string | null {
+  const parsed = parseMonthValue(value)
+  if (!parsed || !Number.isFinite(offset)) return null
+
+  const candidate = new Date(parsed.year, parsed.month - 1 + Math.trunc(offset), 1)
+  return toMonthValue(candidate.getFullYear(), candidate.getMonth() + 1)
+}
+
+export function relativeMonthValue(offset = 0, now = new Date()): string {
+  const candidate = new Date(now.getFullYear(), now.getMonth() + Math.trunc(offset), 1)
+  return toMonthValue(candidate.getFullYear(), candidate.getMonth() + 1)
+}
+
+export function monthValueToDateOnly(value: string | null | undefined): string | null {
+  const normalized = normalizeMonthValue(value)
+  return normalized ? `${normalized}-01` : null
+}
+
+export function dateOnlyToMonthValue(value: string | null | undefined): string | null {
+  const normalized = normalizeDateOnlyValue(value)
+  return normalized ? normalized.slice(0, 7) : null
+}
+
+export function formatMonthValue(
+  value: string | null | undefined,
+  options: Intl.DateTimeFormatOptions = { month: 'long', year: 'numeric' },
+): string | null {
+  const parsed = parseMonthValue(value)
+  if (!parsed) return null
+
+  return new Date(parsed.year, parsed.month - 1, 1).toLocaleString(undefined, options)
+}
+
+export function normalizeDateOnlyValue(value: unknown): string | null {
+  const normalized = String(value ?? '').trim()
+  const match = DATE_ONLY_RE.exec(normalized)
+  if (!match) return null
+
+  const year = Number(match[1])
+  const month = Number(match[2])
+  const day = Number(match[3])
+  if (!Number.isInteger(year) || month < 1 || month > 12 || day < 1 || day > 31) return null
+
+  const candidate = new Date(year, month - 1, day)
+  if (
+    candidate.getFullYear() !== year
+    || candidate.getMonth() !== month - 1
+    || candidate.getDate() !== day
+  ) {
+    return null
+  }
+
+  return `${year}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}`
+}
+
+export function parseDateOnlyValue(value: string | null | undefined): Date | null {
+  const normalized = normalizeDateOnlyValue(value)
+  if (!normalized) return null
+
+  const [year, month, day] = normalized.split('-').map(Number)
+  return new Date(year, month - 1, day)
+}
+
+export function toDateOnlyValue(date: Date): string {
+  return [
+    String(date.getFullYear()).padStart(4, '0'),
+    String(date.getMonth() + 1).padStart(2, '0'),
+    String(date.getDate()).padStart(2, '0'),
+  ].join('-')
+}

package/src/ngb/utils/errorMessage.ts

@@ -0,0 +1,14 @@
+export function toErrorMessage(error: unknown, fallback = 'Request failed.'): string {
+  if (error instanceof Error) {
+    const message = error.message.trim()
+    if (message) return message
+  }
+
+  if (error && typeof error === 'object' && 'message' in error) {
+    const message = String((error as { message?: unknown }).message ?? '').trim()
+    if (message) return message
+  }
+
+  const raw = String(error ?? '').trim()
+  return raw || fallback
+}

package/src/ngb/utils/guid.ts

@@ -0,0 +1,21 @@
+const GUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
+
+export const EMPTY_GUID = '00000000-0000-0000-0000-000000000000'
+
+export function isGuidString(value: unknown): value is string {
+  return typeof value === 'string' && GUID_RE.test(value.trim())
+}
+
+export function isEmptyGuid(value: unknown): boolean {
+  return typeof value === 'string' && value.trim() === EMPTY_GUID
+}
+
+export function isNonEmptyGuid(value: unknown): value is string {
+  return isGuidString(value) && !isEmptyGuid(value)
+}
+
+export function shortGuid(value: unknown): string {
+  const normalized = typeof value === 'string' ? value.trim() : ''
+  if (!normalized) return '—'
+  return normalized.length > 12 ? `${normalized.slice(0, 8)}…${normalized.slice(-4)}` : normalized
+}

package/src/ngb/utils/stableValue.ts

@@ -0,0 +1,21 @@
+function normalizeStableValue(value: unknown, seen: WeakSet<object>): unknown {
+  if (value == null || typeof value !== 'object') return value
+  if (seen.has(value)) return '[Circular]'
+  seen.add(value)
+
+  if (Array.isArray(value)) return value.map((entry) => normalizeStableValue(entry, seen))
+
+  const output: Record<string, unknown> = {}
+  for (const key of Object.keys(value).sort()) {
+    output[key] = normalizeStableValue((value as Record<string, unknown>)[key], seen)
+  }
+  return output
+}
+
+export function stableStringify(value: unknown): string {
+  return JSON.stringify(normalizeStableValue(value, new WeakSet<object>()))
+}
+
+export function stableEquals(left: unknown, right: unknown): boolean {
+  return stableStringify(left) === stableStringify(right)
+}

package/src/ngb/utils/storage.ts

@@ -0,0 +1,135 @@
+export type StorageScope = 'local' | 'session'
+
+export type CookieOptions = {
+  path?: string
+  maxAgeSeconds?: number
+  sameSite?: 'Lax' | 'Strict' | 'None'
+  secure?: boolean
+  domain?: string | null
+}
+
+function resolveBrowserStorage(scope: StorageScope): Storage | null {
+  if (typeof window === 'undefined') return null
+
+  try {
+    return scope === 'session' ? window.sessionStorage : window.localStorage
+  } catch {
+    return null
+  }
+}
+
+export function canUseStorage(scope: StorageScope): boolean {
+  return resolveBrowserStorage(scope) !== null
+}
+
+export function readStorageString(scope: StorageScope, key: string): string | null {
+  const storage = resolveBrowserStorage(scope)
+  if (!storage) return null
+
+  try {
+    return storage.getItem(key)
+  } catch {
+    return null
+  }
+}
+
+export function writeStorageString(scope: StorageScope, key: string, value: string): boolean {
+  const storage = resolveBrowserStorage(scope)
+  if (!storage) return false
+
+  try {
+    storage.setItem(key, value)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function removeStorageItem(scope: StorageScope, key: string): void {
+  const storage = resolveBrowserStorage(scope)
+  if (!storage) return
+
+  try {
+    storage.removeItem(key)
+  } catch {
+    // Ignore storage cleanup failures.
+  }
+}
+
+export function listStorageKeys(scope: StorageScope): string[] {
+  const storage = resolveBrowserStorage(scope)
+  if (!storage) return []
+
+  try {
+    return Object.keys(storage)
+  } catch {
+    return []
+  }
+}
+
+export function readStorageJson<T>(scope: StorageScope, key: string, fallback: T): T {
+  const raw = readStorageString(scope, key)
+  if (!raw) return fallback
+
+  try {
+    return JSON.parse(raw) as T
+  } catch {
+    return fallback
+  }
+}
+
+export function readStorageJsonOrNull<T>(scope: StorageScope, key: string): T | null {
+  const raw = readStorageString(scope, key)
+  if (!raw) return null
+
+  try {
+    return JSON.parse(raw) as T
+  } catch {
+    return null
+  }
+}
+
+export function writeStorageJson(scope: StorageScope, key: string, value: unknown): boolean {
+  try {
+    return writeStorageString(scope, key, JSON.stringify(value))
+  } catch {
+    return false
+  }
+}
+
+export function loadJson<T>(key: string, fallback: T): T {
+  return readStorageJson('local', key, fallback)
+}
+
+export function saveJson(key: string, value: unknown): void {
+  void writeStorageJson('local', key, value)
+}
+
+export function readCookie(name: string): string | null {
+  if (typeof document === 'undefined') return null
+
+  const prefix = `${name}=`
+  const cookie = document.cookie
+    .split(';')
+    .map((part) => part.trim())
+    .find((part) => part.startsWith(prefix))
+
+  if (!cookie) return null
+  return decodeURIComponent(cookie.slice(prefix.length))
+}
+
+export function writeCookie(name: string, value: string, options: CookieOptions = {}): void {
+  if (typeof document === 'undefined') return
+
+  const parts = [
+    `${name}=${encodeURIComponent(value)}`,
+    `Path=${options.path ?? '/'}`,
+    `SameSite=${options.sameSite ?? 'Lax'}`,
+  ]
+
+  if (Number.isFinite(options.maxAgeSeconds)) parts.push(`Max-Age=${Math.max(0, Math.floor(options.maxAgeSeconds ?? 0))}`)
+  if (options.secure) parts.push('Secure')
+  if (options.domain) parts.push(`Domain=${options.domain}`)
+
+  document.cookie = parts.join('; ')
+}

package/src/styles/tailwind.css

@@ -0,0 +1,165 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/* NGB Design Tokens (CSS vars for theming) */
+:root {
+  /* Make native form controls (date picker, number spinners, etc.) render in a light theme by default. */
+  color-scheme: light;
+  --ngb-blue: #0B3C5D;
+  --ngb-blue-dark: #072A40;
+  --ngb-blue-hover: #0E4A75;
+  --ngb-primary-rgb: 11 60 93;
+  --ngb-primary-hover-rgb: 14 74 117;
+
+  /* Brand logo */
+  --ngb-logo: #0B3C5D;
+  --ngb-logo-accent: #0F766E;
+
+  --ngb-text: #1F2933;
+  --ngb-muted: #4B5563;
+  --ngb-border: #CBD5E1;
+  --ngb-bg: #F5F7FA;
+  --ngb-card: #FFFFFF;
+
+  --ngb-danger: #9B1C1C;
+  --ngb-warn: #B45309;
+  --ngb-success: #2E7D32;
+  --ngb-neutral-subtle: #F1F5F9;
+  --ngb-success-subtle: #F3FBF4;
+  --ngb-warn-subtle: #FFF7ED;
+  --ngb-danger-subtle: #FEF2F2;
+  --ngb-success-border: rgba(46,125,50,.35);
+  --ngb-warn-border: rgba(180,83,9,.35);
+  --ngb-danger-border: rgba(155,28,28,.35);
+
+  --ngb-accent-1: #006D6F;
+  --ngb-accent-2: #5B2D8B;
+  --ngb-accent-3: #C05621;
+  --ngb-accent-4: #B45309;
+
+  /* Spacing scale (4/8/12/16/24/32) */
+  --ngb-space-4: 4px;
+  --ngb-space-8: 8px;
+  --ngb-space-12: 12px;
+  --ngb-space-16: 16px;
+  --ngb-space-24: 24px;
+  --ngb-space-32: 32px;
+
+  /* Minimal elevation */
+  --ngb-shadow-0: none;
+  --ngb-shadow-1: 0 6px 24px rgba(0,0,0,.08);
+  --ngb-shadow-2: 0 12px 38px rgba(0,0,0,.12);
+
+  --ngb-radius: 4px;
+
+  /* Grid surfaces */
+  --ngb-grid-header: #F1F5F9;
+  --ngb-row-hover: #F8FAFC;
+  --ngb-row-selected: #EEF6FF;
+}
+
+/* Dark theme (minimal, ERP-friendly) */
+html.dark {
+  /* Native form controls (date picker, number spinners, etc.) should follow dark theme. */
+  color-scheme: dark;
+  --ngb-text: #E5E7EB;
+  --ngb-muted: #9CA3AF;
+  --ngb-border: #1F2937;
+  --ngb-bg: #0B1220;
+  --ngb-card: #0F172A;
+
+  /* brand */
+  --ngb-blue-hover: #0F5F95;
+  --ngb-primary-hover-rgb: 15 95 149;
+
+  /* Brand logo: lighter for contrast in dark mode */
+  --ngb-logo: #93C5FD;
+  --ngb-logo-accent: #34D399;
+
+  /* statuses */
+  --ngb-danger: #F87171;
+  --ngb-warn: #FBBF24;
+  --ngb-success: #34D399;
+  --ngb-neutral-subtle: rgba(255,255,255,.06);
+  --ngb-success-subtle: rgba(52,211,153,.12);
+  --ngb-warn-subtle: rgba(251,191,36,.12);
+  --ngb-danger-subtle: rgba(248,113,113,.12);
+  --ngb-success-border: rgba(52,211,153,.35);
+  --ngb-warn-border: rgba(251,191,36,.35);
+  --ngb-danger-border: rgba(248,113,113,.35);
+
+  --ngb-shadow-1: 0 10px 34px rgba(0,0,0,.45);
+  --ngb-shadow-2: 0 18px 52px rgba(0,0,0,.55);
+
+  /* Grid surfaces */
+  --ngb-grid-header: #0B1220;
+  --ngb-row-hover: #101B33;
+  --ngb-row-selected: #122A46;
+}
+
+/* --------------------------------------
+   Native inputs: dark-mode ergonomics
+   -------------------------------------- */
+
+/* Keep number inputs ERP-clean: remove native spinners (they render poorly across OS/themes). */
+input[type='number']::-webkit-outer-spin-button,
+input[type='number']::-webkit-inner-spin-button {
+  -webkit-appearance: none;
+  margin: 0;
+}
+input[type='number'] {
+  -moz-appearance: textfield;
+  appearance: textfield;
+}
+
+@layer base {
+  html, body { height: 100%; }
+  body {
+    @apply bg-ngb-bg text-ngb-text;
+    font-family: system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial, "Apple Color Emoji","Segoe UI Emoji";
+  }
+}
+
+@layer utilities {
+  .ngb-focus {
+    @apply outline-none ring-0 focus-visible:ring-4 focus-visible:ring-[rgba(11,60,93,.12)] focus-visible:border-[rgba(11,60,93,.55)];
+  }
+
+  /* Icon-only button (ChatGPT/QuickBooks-like) */
+  .ngb-iconbtn {
+    @apply h-9 w-9 rounded-[var(--ngb-radius)] flex items-center justify-center
+      text-ngb-muted hover:text-ngb-text hover:bg-ngb-bg
+      transition-colors cursor-pointer ngb-focus
+      disabled:opacity-40 disabled:cursor-not-allowed disabled:hover:bg-transparent disabled:hover:text-ngb-muted;
+  }
+
+  .ngb-card {
+    @apply rounded-[var(--ngb-radius)] border border-ngb-border bg-ngb-card shadow-card;
+  }
+
+  .ngb-divider { @apply bg-ngb-border; }
+
+  .ngb-mono {
+    font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+  }
+
+  /* Numeric alignment (ERP-like) */
+  .ngb-num { font-variant-numeric: tabular-nums; text-align: right; }
+  .ngb-num-inline { font-variant-numeric: tabular-nums; }
+
+  .ngb-spinner {
+    width: 14px;
+    height: 14px;
+    border: 2px solid rgba(11,60,93,.18);
+    border-top-color: rgba(11,60,93,.65);
+    border-radius: 999px;
+    animation: ngb-spin 700ms linear infinite;
+  }
+  @keyframes ngb-spin { to { transform: rotate(360deg); } }
+
+  .ngb-kbd {
+    @apply px-1.5 py-0.5 rounded-[var(--ngb-radius)] border border-ngb-border bg-ngb-card text-[11px] text-ngb-muted;
+    font-variant-numeric: tabular-nums;
+  }
+}

package/src/vite/publicAssets.ts

@@ -0,0 +1,104 @@
+import { readFileSync } from 'node:fs'
+
+type DevRequestLike = {
+  url?: string
+}
+
+type DevResponseLike = {
+  statusCode: number
+  setHeader: (name: string, value: string) => void
+  end: (body?: string | Uint8Array) => void
+}
+
+type DevServerLike = {
+  middlewares: {
+    use: (handler: (req: DevRequestLike, res: DevResponseLike, next: () => void) => void) => void
+  }
+}
+
+type AssetEmitterLike = {
+  emitFile: (asset: {
+    type: 'asset'
+    fileName: string
+    source: string | Uint8Array
+  }) => void
+}
+
+type PublicAssetDefinition = {
+  requestPath: string
+  fileName: string
+  contentType: string
+  source: string | Uint8Array
+}
+
+export type NgbUiFrameworkPublicAssetsPluginOptions = {
+  faviconFileName?: string
+  silentCheckSsoFileName?: string
+}
+
+function normalizePublicFileName(value: string | null | undefined, fallback: string): string {
+  const normalized = String(value ?? '').trim().replace(/^\/+/, '')
+  return normalized || fallback
+}
+
+function readUiFrameworkPublicAsset(relativePath: string, encoding?: BufferEncoding): string | Uint8Array {
+  const url = new URL(`../../public/${relativePath}`, import.meta.url)
+  return encoding ? readFileSync(url, encoding) : readFileSync(url)
+}
+
+function buildPublicAssets(options: NgbUiFrameworkPublicAssetsPluginOptions): PublicAssetDefinition[] {
+  return [
+    {
+      requestPath: '/favicon.svg',
+      fileName: normalizePublicFileName(options.faviconFileName, 'favicon.svg'),
+      contentType: 'image/svg+xml; charset=utf-8',
+      source: readUiFrameworkPublicAsset('favicon.svg'),
+    },
+    {
+      requestPath: '/silent-check-sso.html',
+      fileName: normalizePublicFileName(options.silentCheckSsoFileName, 'silent-check-sso.html'),
+      contentType: 'text/html; charset=utf-8',
+      source: readUiFrameworkPublicAsset('silent-check-sso.html', 'utf8'),
+    },
+  ]
+}
+
+function requestPathname(url: string | undefined): string {
+  try {
+    return new URL(url ?? '/', 'http://localhost').pathname
+  } catch {
+    return '/'
+  }
+}
+
+export function ngbUiFrameworkPublicAssetsPlugin(options: NgbUiFrameworkPublicAssetsPluginOptions = {}) {
+  const assets = buildPublicAssets(options)
+
+  return {
+    name: 'ngb-ui-framework-public-assets',
+    configureServer(server: DevServerLike) {
+      server.middlewares.use((req, res, next) => {
+        const pathname = requestPathname(req.url)
+        const asset = assets.find((entry) => entry.requestPath === pathname)
+
+        if (!asset) {
+          next()
+          return
+        }
+
+        res.statusCode = 200
+        res.setHeader('Content-Type', asset.contentType)
+        res.end(asset.source)
+      })
+    },
+    generateBundle(this: AssetEmitterLike) {
+      for (const asset of assets) {
+        this.emitFile({
+          type: 'asset',
+          fileName: asset.fileName,
+          source: asset.source,
+        })
+      }
+    },
+  }
+}

package/vite-public-assets.js

@@ -0,0 +1,68 @@
+import { readFileSync } from 'node:fs'
+
+function normalizePublicFileName(value, fallback) {
+  const normalized = String(value ?? '').trim().replace(/^\/+/, '')
+  return normalized || fallback
+}
+
+function readUiFrameworkPublicAsset(relativePath, encoding) {
+  const url = new URL(`./public/${relativePath}`, import.meta.url)
+  return encoding ? readFileSync(url, encoding) : readFileSync(url)
+}
+
+function buildPublicAssets(options) {
+  return [
+    {
+      requestPath: '/favicon.svg',
+      fileName: normalizePublicFileName(options.faviconFileName, 'favicon.svg'),
+      contentType: 'image/svg+xml; charset=utf-8',
+      source: readUiFrameworkPublicAsset('favicon.svg'),
+    },
+    {
+      requestPath: '/silent-check-sso.html',
+      fileName: normalizePublicFileName(options.silentCheckSsoFileName, 'silent-check-sso.html'),
+      contentType: 'text/html; charset=utf-8',
+      source: readUiFrameworkPublicAsset('silent-check-sso.html', 'utf8'),
+    },
+  ]
+}
+
+function requestPathname(url) {
+  try {
+    return new URL(url ?? '/', 'http://localhost').pathname
+  } catch {
+    return '/'
+  }
+}
+
+export function ngbUiFrameworkPublicAssetsPlugin(options = {}) {
+  const assets = buildPublicAssets(options)
+
+  return {
+    name: 'ngb-ui-framework-public-assets',
+    configureServer(server) {
+      server.middlewares.use((req, res, next) => {
+        const pathname = requestPathname(req.url)
+        const asset = assets.find((entry) => entry.requestPath === pathname)
+
+        if (!asset) {
+          next()
+          return
+        }
+
+        res.statusCode = 200
+        res.setHeader('Content-Type', asset.contentType)
+        res.end(asset.source)
+      })
+    },
+    generateBundle() {
+      for (const asset of assets) {
+        this.emitFile({
+          type: 'asset',
+          fileName: asset.fileName,
+          source: asset.source,
+        })
+      }
+    },
+  }
+}