kmcom-nuxt-layers 6.0.0 → 6.2.0

package/layers/core/app/plugins/loading.client.ts

@@ -1,24 +1,17 @@
 // plugins/loading.client.ts
 
-type LoadingConfig = {
-  enabled?: boolean
-  minDuration?: number
-  maxDuration?: number
-  background?: string
-  textColor?: string
-  zIndex?: number
-}
-
-type CoreLayerConfig = {
-  loading?: LoadingConfig
-}
+import { resolveLoadingConfig } from '../utils/loading'
 
 /**
  * Loading screen initialization plugin
  *
- * Runs on app mount (client-side only) to:
- * 1. Start simulated progress on page load
- * 2. Stop loading when app is fully mounted and hydrated
+ * Client-side only. Once the app has mounted (hydration done) it:
+ * 1. Starts the progress count, timed from navigation start - the SSR'd screen has been up
+ *    since first paint, so the count catches up smoothly rather than starting late
+ * 2. Waits for fonts and the initial page's images, capped at `maxDuration`
+ * 3. Marks loading done - the count then finishes to 100 before the screen exits
+ *
+ * Starting after mount keeps the counter at the SSR'd 0 through hydration (no mismatch).
  *
  * Configuration via app.config.ts:
  * - Set `coreLayer.loading.enabled: false` to disable
@@ -26,26 +19,27 @@ type CoreLayerConfig = {
 export default defineNuxtPlugin({
   name: 'core:loading',
   setup(nuxtApp) {
-    const config = useAppConfig()
-    const coreLayer = config.coreLayer as CoreLayerConfig | undefined
+    const { enabled, maxDuration } = resolveLoadingConfig(useAppConfig().coreLayer)
 
     // Check if loading is enabled
-    if (coreLayer?.loading?.enabled === false) {
+    if (!enabled) {
       return // Disabled, skip initialization
     }
 
     const { startLoading, stopLoading } = useLoading()
 
-    // Start loading immediately on plugin load
-    startLoading()
-
-    // Stop loading when app is fully mounted
+    // Not awaited: app:mounted handlers run serially, so waiting here would hold up other layers
     nuxtApp.hook('app:mounted', () => {
-      // Add a small delay to ensure LoadingScreen component has mounted
-      // and is visible before we stop loading
-      setTimeout(() => {
-        stopLoading()
-      }, 500) // 500ms delay to ensure component is visible
+      startLoading(0)
+      void Promise.race([
+        Promise.all([pageLoaded(), document.fonts?.ready]),
+        new Promise((resolve) => setTimeout(resolve, maxDuration)),
+      ]).then(stopLoading)
     })
   },
 })
+
+function pageLoaded(): Promise<unknown> {
+  if (document.readyState === 'complete') return Promise.resolve()
+  return new Promise((resolve) => window.addEventListener('load', resolve, { once: true }))
+}

package/layers/core/app/types/loading.ts

@@ -6,10 +6,12 @@
 export type LoadingConfig = {
   /** Master toggle - set to false to disable completely */
   enabled: boolean
-  /** Minimum time to display loading screen (prevents flash) */
+  /** Minimum time (ms, from navigation start) the count runs before it may reach 100 */
   minDuration: number
-  /** Maximum time for simulated progress */
+  /** Longest wait (ms, after the app mounts) for fonts and images before finishing anyway */
   maxDuration: number
+  /** Small caption above the counter - empty string hides it */
+  label: string
   /** Background color */
   background: string
   /** Progress text color */
@@ -18,6 +20,12 @@ export type LoadingConfig = {
   zIndex: number
 }
 
+/**
+ * Boot loading screen lifecycle, shared so other layers can hold their own motion until the
+ * page is revealed: covering the page → playing its exit → gone (or never mounted)
+ */
+export type LoadingScreenState = 'visible' | 'leaving' | 'hidden'
+
 /**
  * Loading state interface
  */
@@ -32,15 +40,17 @@ export type LoadingState = {
  * Loading composable return interface
  */
 export type UseLoadingReturn = {
-  /** Current loading state (readonly) */
+  /** True until the displayed progress has counted up to 100 (readonly) */
   isLoading: Readonly<Ref<boolean>>
-  /** Progress percentage 0-100 (readonly) */
+  /** Displayed progress 0-100, eased every frame - never jumps or moves backwards (readonly) */
   progress: Readonly<Ref<number>>
-  /** Start loading with simulated progress */
-  startLoading: () => void
-  /** Stop loading and jump to 100% */
+  /** Boot loading screen lifecycle (readonly) */
+  screen: Readonly<Ref<LoadingScreenState>>
+  /** Start simulated progress, timed from `since` (a `performance.now()` value; default now) */
+  startLoading: (since?: number) => void
+  /** Mark work done - the count finishes to 100 once `minDuration` has passed */
   stopLoading: () => void
-  /** Manually update progress (0-100) */
+  /** Raise the progress floor (0-99) - only `stopLoading` completes */
   updateProgress: (value: number) => void
   /** Execute async function with loading state */
   withLoading: (fn: () => Promise<void>) => Promise<void>

package/layers/core/app/utils/index.ts

@@ -6,5 +6,6 @@
 
 export * from './browserInfo'
 export * from './featureClasses'
+export * from './loading'
 export * from './scrollGuardClamp'
 export * from './styleToTailwindClasses'

package/layers/core/app/utils/loading.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vite-plus/test'
+
+import { approachProgress, resolveLoadingConfig, trickleProgress } from './loading'
+
+const FRAME = 1 / 60
+
+describe('resolveLoadingConfig', () => {
+  it('fills unset keys with defaults but keeps falsy values that were set', () => {
+    expect(resolveLoadingConfig(undefined)).toMatchObject({ enabled: true, minDuration: 1500 })
+    expect(resolveLoadingConfig({ loading: { minDuration: 0, label: '' } })).toMatchObject({
+      enabled: true,
+      minDuration: 0,
+      label: '',
+    })
+  })
+})
+
+describe('trickleProgress', () => {
+  it('starts at 0, rises with time, and stays below the cap', () => {
+    expect(trickleProgress(0, 1200)).toBe(0)
+    expect(trickleProgress(-500, 1200)).toBe(0)
+    expect(trickleProgress(1200, 1200)).toBeGreaterThan(trickleProgress(600, 1200))
+    expect(trickleProgress(60_000, 1200)).toBeLessThanOrEqual(90)
+  })
+})
+
+describe('approachProgress', () => {
+  it('counts 0 → 100 in small per-frame steps and lands exactly on the target', () => {
+    let current = 0
+    let frames = 0
+    while (current < 100) {
+      const next = approachProgress(current, 100, FRAME)
+      expect(next).toBeGreaterThan(current)
+      expect(Math.floor(next) - Math.floor(current)).toBeLessThanOrEqual(3)
+      current = next
+      frames++
+    }
+    expect(current).toBe(100)
+    // A visible count of at least ~0.7s, not a jump
+    expect(frames).toBeGreaterThan(40)
+  })
+
+  it('never moves backwards or overshoots', () => {
+    expect(approachProgress(60, 40, FRAME)).toBe(60)
+    expect(approachProgress(0, 90, -0.008)).toBe(0)
+    expect(approachProgress(99.9, 100, 1)).toBe(100)
+  })
+})

package/layers/core/app/utils/loading.ts

@@ -0,0 +1,53 @@
+import type { LoadingConfig } from '../types/loading'
+
+/** Fallbacks for keys app.config leaves unset - core's app.config ships the same values. */
+const LOADING_DEFAULTS: LoadingConfig = {
+  enabled: true,
+  minDuration: 1500,
+  maxDuration: 3000,
+  label: 'Loading',
+  background: '#0a0a0a',
+  textColor: '#ffffff',
+  zIndex: 10000,
+}
+
+/** Reads `coreLayer.loading` from app config, filling unset keys with the defaults. */
+export function resolveLoadingConfig(coreLayer: unknown): LoadingConfig {
+  const loading = (coreLayer as { loading?: Partial<LoadingConfig> } | undefined)?.loading
+  return { ...LOADING_DEFAULTS, ...loading }
+}
+
+/*
+ * Pure easing math behind `useLoading`'s progress counter. `useLoading` runs these once per
+ * animation frame: `trickleProgress` moves the target, `approachProgress` moves the displayed
+ * value toward it, so the counter climbs smoothly instead of jumping between random values.
+ */
+
+/** Simulated progress stays below this until loading actually finishes. */
+const TRICKLE_CAP = 90
+/** Time constant (s) of the displayed value's exponential ease toward its target. */
+const EASE = 0.15
+/** Speed band (%/s) for the displayed value: no crawling at the tail, no leaps on big jumps. */
+const MIN_SPEED = 24
+const MAX_SPEED = 140
+
+/**
+ * Simulated progress `elapsed` ms after loading started: quick at first, then slowing as it
+ * approaches the cap. `tau` (ms) sets the pace — ~63% of the cap is reached after `tau`.
+ */
+export function trickleProgress(elapsed: number, tau: number): number {
+  return TRICKLE_CAP * (1 - Math.exp(-Math.max(elapsed, 0) / tau))
+}
+
+/**
+ * Advances `current` toward `target` over `dt` seconds. Eases out as the gap closes, within the
+ * speed band, and never moves backwards or past `target`. A rAF timestamp can precede the
+ * `performance.now()` the loop started from, so `dt <= 0` is a no-op rather than a step back.
+ */
+export function approachProgress(current: number, target: number, dt: number): number {
+  const gap = target - current
+  if (gap <= 0 || dt <= 0) return current
+  const eased = gap * (1 - Math.exp(-dt / EASE))
+  const step = Math.min(Math.max(eased, MIN_SPEED * dt), MAX_SPEED * dt)
+  return Math.min(current + step, target)
+}

package/layers/core/app/utils/resolveElementStyle.test.ts

@@ -87,9 +87,9 @@ describe('resolveElementStyle prop mapping', () => {
   it('merges layout attrs (gap/align/padding) into the same object', () => {
     expect(resolveElementStyle({ flex: true, gap: 'md', align: 'center', p: 'sm' })).toMatchObject({
       display: 'flex',
-      gap: 'var(--fluid-space-md)',
+      gap: 'var(--space-md)',
       alignItems: 'center',
-      padding: 'var(--fluid-space-sm)',
+      padding: 'var(--space-sm)',
     })
   })
 

package/layers/design-system/theming/app/types/designSystem.ts

@@ -7,19 +7,21 @@
  * (theme adapter component overrides, standalone token exports) will import
  * it directly.
  */
-import type { FluidFontSize } from '#layers/typography/app/types/typography'
+import type { TypeStep } from '#layers/typography/app/types/typography'
 import type { UiColors } from '#types'
 
 /**
  * Design-system tokens — first real config-object source of truth (Phase 5,
  * nuxt-declarative-layout-system-spec.md §21). Colours key off the existing
  * `UiColors` union rather than inventing new names; typography keys off the
- * existing `FluidFontSize` scale/CSS vars in layers/typography — this section
+ * existing `TypeStep` modular scale/CSS vars in layers/typography — this section
  * only gives them a config-object home so a Nuxt UI theme adapter and CSS
  * custom properties can derive from one place.
  */
 
-const fluidTextVar = (size: FluidFontSize) => `var(--fluid-text-${size}-raw)`
+// Unrounded size of one step — typography.css's text-step-* utilities also round() it.
+const stepSize = (exponent: number | string) =>
+  `calc(var(--type-base) * pow(var(--type-scale), ${exponent}))`
 
 export const designSystem = {
   colors: {
@@ -59,20 +61,22 @@ export const designSystem = {
   },
 
   typography: {
-    xs: fluidTextVar('xs'),
-    sm: fluidTextVar('sm'),
-    md: fluidTextVar('md'),
-    lg: fluidTextVar('lg'),
-    xl: fluidTextVar('xl'),
-    '2xl': fluidTextVar('2xl'),
-    '3xl': fluidTextVar('3xl'),
-    '4xl': fluidTextVar('4xl'),
-    '5xl': fluidTextVar('5xl'),
-    '6xl': fluidTextVar('6xl'),
-    '7xl': fluidTextVar('7xl'),
-    '8xl': fluidTextVar('8xl'),
-    '9xl': fluidTextVar('9xl'),
-  },
+    sm: stepSize(-1),
+    0: stepSize(0),
+    1: stepSize(1),
+    2: stepSize(2),
+    3: stepSize(3),
+    4: stepSize(4),
+    5: stepSize(5),
+    6: stepSize(6),
+    7: stepSize(7),
+    8: stepSize(8),
+    9: stepSize(9),
+    10: stepSize(10),
+    11: stepSize(11),
+    12: stepSize(12),
+    display: stepSize('var(--step-display)'),
+  } satisfies Record<TypeStep, string>,
 
   motion: {
     duration: {

package/layers/design-system/typography/app/app.config.ts

@@ -0,0 +1,26 @@
+import { TYPE_STEP_CLASSES } from './composables/typography'
+
+// Nuxt UI prose (Nuxt Content) on the modular scale. Nuxt UI pins prose headings to
+// text-4xl/2xl/xl/lg and p/li to leading-7 with no size, so with a 20/24px body the copy sat
+// at or above h2/h3 size on a cramped 28px line. Headings take their step instead (h1 one step
+// above h2, not the display step — content pages already show a page-header title); copy keeps
+// inheriting the body step, with the body's 1.7 leading.
+export default defineAppConfig({
+  ui: {
+    // tailwind-merge reads unknown text-* classes as a text colour, so a step class would drop
+    // a component's colour class and keep its text-{size}. Register them as font sizes.
+    tv: {
+      twMergeConfig: {
+        extend: { classGroups: { 'font-size': Object.values(TYPE_STEP_CLASSES) } },
+      },
+    },
+    prose: {
+      h1: { slots: { base: 'text-step-4' } },
+      h2: { slots: { base: 'text-step-3' } },
+      h3: { slots: { base: 'text-step-2' } },
+      h4: { slots: { base: 'text-step-1' } },
+      p: { base: 'leading-[1.7]' },
+      li: { base: 'leading-[1.7]' },
+    },
+  },
+})