@larose-ui/core 0.1.1 → 0.1.2

package/dist/index.d.ts

@@ -157,6 +157,56 @@ declare function createCompositeFeatureFlagEvaluator(evaluators: FeatureFlagEval
 declare function detectA11yPreferences(): A11yPreferences;
 declare function subscribeA11yPreferences(onChange: (preferences: A11yPreferences) => void): () => void;
 
+/** Physics parameters for spring simulation (mass-normalized). */
+interface SpringConfig {
+    stiffness: number;
+    damping: number;
+    mass?: number;
+}
+type SpringPresetName = 'snappy' | 'smooth' | 'gentle' | 'responsive' | 'bouncy';
+interface SpringState {
+    value: number;
+    velocity: number;
+}
+type ReducedMotionPolicy = 'system' | 'always' | 'never';
+type MotionSemanticPreset = SpringPresetName | 'none';
+
+/** Apple-inspired spring presets — tuned for UI hierarchy. */
+declare const SPRING_PRESETS: Record<SpringPresetName, SpringConfig>;
+declare function getSpringPreset(name: SpringPresetName): SpringConfig;
+/**
+ * Advance a spring simulation by one timestep (seconds).
+ * Uses implicit Euler integration — stable for UI frame rates.
+ */
+declare function stepSpring(state: SpringState, target: number, config: SpringConfig, deltaTime: number): SpringState;
+/** Returns true when the spring has settled near the target. */
+declare function isSpringSettled(state: SpringState, target: number, precision?: number, velocityPrecision?: number): boolean;
+/**
+ * Animate a spring to completion over discrete steps.
+ * Useful for tests and non-RAF environments.
+ */
+declare function animateSpringToTarget(from: number, target: number, config: SpringConfig, options?: {
+    velocity?: number;
+    maxSteps?: number;
+    deltaTime?: number;
+}): SpringState;
+/** Approximate spring response time in seconds (for duration hints). */
+declare function springResponseTime(config: SpringConfig): number;
+
+declare function resolveReducedMotion(policy: ReducedMotionPolicy, systemPrefersReduced: boolean): boolean;
+/** Scale motion duration to zero when reduced motion is active. */
+declare function motionDuration(durationMs: number, reducedMotion: boolean): number;
+
+/**
+ * Returns a safe href for in-app navigation, or undefined when the URL is unsafe.
+ * Blocks javascript:, data:, vbscript:, blob:, and protocol-relative URLs.
+ */
+declare function sanitizeNavigationUrl(url: string | undefined): string | undefined;
+/**
+ * Validates same-origin relative redirect targets (e.g. login paths).
+ */
+declare function isSafeRedirectPath(url: string): boolean;
+
 /**
  * UI component lifecycle states supported across laRose.
  */
@@ -214,6 +264,9 @@ interface VersionInfo {
 }
 type Variant = 'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive';
 type Size = 'sm' | 'md' | 'lg';
+/** Apple HIG button semantic roles — style, content, and role. */
+type ButtonRole = 'normal' | 'primary' | 'cancel' | 'destructive';
+type TypographyRole = 'display' | 'largeTitle' | 'title' | 'headline' | 'body' | 'callout' | 'subheadline' | 'footnote' | 'caption';
 interface ComponentStateProps {
     state?: UIState;
     loading?: boolean;
@@ -230,4 +283,4 @@ declare function createEventEmitter<T extends Record<string, unknown>>(): {
 };
 declare const LAROSE_VERSION = "0.1.0";
 
-export { type A11yPreferences, type ApiError, type AsyncEvent, type AsyncState, type AsyncStateMachine, type ComponentStateProps, type Density, type Environment, type FeatureFlagEvaluationContext, type FeatureFlagEvaluator, type FeatureFlagResult, type FeatureFlagSnapshot, type HttpErrorCode, LAROSE_VERSION, type LaRoseRuntimeContext, type LocaleSnapshot, type NetworkCondition, type NetworkSnapshot, type OfflineSnapshot, type PercentageRolloutConfig, type Permission, type PermissionFallback, type PermissionSnapshot, type RuntimeEvent, type RuntimeEventBus, type RuntimeEventType, type SessionEvent, type SessionState, type SessionStateMachine, type Size, type StaticFeatureFlagValue, type TenantContext, type ThemeMode, type ThemeSnapshot, type UIState, type UserContext, type Variant, type VersionInfo, type VersionMatrix, classifyHttpError, createAsyncStateMachine, createCompositeFeatureFlagEvaluator, createDefaultRuntimeContext, createEventEmitter, createPercentageRolloutEvaluator, createRuntimeEventBus, createSessionStateMachine, createStaticFeatureFlagEvaluator, detectA11yPreferences, resetDeprecationWarnings, resolveUIState, subscribeA11yPreferences, warnDeprecation };
+export { type A11yPreferences, type ApiError, type AsyncEvent, type AsyncState, type AsyncStateMachine, type ButtonRole, type ComponentStateProps, type Density, type Environment, type FeatureFlagEvaluationContext, type FeatureFlagEvaluator, type FeatureFlagResult, type FeatureFlagSnapshot, type HttpErrorCode, LAROSE_VERSION, type LaRoseRuntimeContext, type LocaleSnapshot, type MotionSemanticPreset, type NetworkCondition, type NetworkSnapshot, type OfflineSnapshot, type PercentageRolloutConfig, type Permission, type PermissionFallback, type PermissionSnapshot, type ReducedMotionPolicy, type RuntimeEvent, type RuntimeEventBus, type RuntimeEventType, SPRING_PRESETS, type SessionEvent, type SessionState, type SessionStateMachine, type Size, type SpringConfig, type SpringPresetName, type SpringState, type StaticFeatureFlagValue, type TenantContext, type ThemeMode, type ThemeSnapshot, type TypographyRole, type UIState, type UserContext, type Variant, type VersionInfo, type VersionMatrix, animateSpringToTarget, classifyHttpError, createAsyncStateMachine, createCompositeFeatureFlagEvaluator, createDefaultRuntimeContext, createEventEmitter, createPercentageRolloutEvaluator, createRuntimeEventBus, createSessionStateMachine, createStaticFeatureFlagEvaluator, detectA11yPreferences, getSpringPreset, isSafeRedirectPath, isSpringSettled, motionDuration, resetDeprecationWarnings, resolveReducedMotion, resolveUIState, sanitizeNavigationUrl, springResponseTime, stepSpring, subscribeA11yPreferences, warnDeprecation };

package/dist/index.js

@@ -210,6 +210,96 @@ function subscribeA11yPreferences(onChange) {
   };
 }
 
+// src/motion/springs.ts
+var SPRING_PRESETS = {
+  /** Small UI feedback — buttons, toggles. */
+  responsive: { stiffness: 380, damping: 32, mass: 1 },
+  /** Snappy menus, dropdowns. */
+  snappy: { stiffness: 320, damping: 28, mass: 1 },
+  /** Modal / dialog entrance. */
+  smooth: { stiffness: 220, damping: 26, mass: 1 },
+  /** Drawer, sheet movement. */
+  gentle: { stiffness: 180, damping: 24, mass: 1 },
+  /** Playful emphasis — use sparingly. */
+  bouncy: { stiffness: 260, damping: 18, mass: 1 }
+};
+function getSpringPreset(name) {
+  return { ...SPRING_PRESETS[name] };
+}
+function stepSpring(state, target, config, deltaTime) {
+  const mass = config.mass ?? 1;
+  const stiffness = config.stiffness;
+  const damping = config.damping;
+  const displacement = state.value - target;
+  const springForce = -stiffness * displacement;
+  const dampingForce = -damping * state.velocity;
+  const acceleration = (springForce + dampingForce) / mass;
+  const velocity = state.velocity + acceleration * deltaTime;
+  const value = state.value + velocity * deltaTime;
+  return { value, velocity };
+}
+function isSpringSettled(state, target, precision = 1e-3, velocityPrecision = 0.01) {
+  return Math.abs(state.value - target) < precision && Math.abs(state.velocity) < velocityPrecision;
+}
+function animateSpringToTarget(from, target, config, options = {}) {
+  const maxSteps = options.maxSteps ?? 600;
+  const deltaTime = options.deltaTime ?? 1 / 60;
+  let state = { value: from, velocity: options.velocity ?? 0 };
+  for (let i = 0; i < maxSteps; i++) {
+    state = stepSpring(state, target, config, deltaTime);
+    if (isSpringSettled(state, target)) break;
+  }
+  return state;
+}
+function springResponseTime(config) {
+  const mass = config.mass ?? 1;
+  const omega = Math.sqrt(config.stiffness / mass);
+  const zeta = config.damping / (2 * Math.sqrt(config.stiffness * mass));
+  if (zeta < 1) {
+    return 2 * Math.PI / (omega * Math.sqrt(1 - zeta * zeta));
+  }
+  return 4 / (zeta * omega);
+}
+
+// src/motion/reduced.ts
+function resolveReducedMotion(policy, systemPrefersReduced) {
+  switch (policy) {
+    case "always":
+      return true;
+    case "never":
+      return false;
+    case "system":
+    default:
+      return systemPrefersReduced;
+  }
+}
+function motionDuration(durationMs, reducedMotion) {
+  return reducedMotion ? 0 : durationMs;
+}
+
+// src/security/url.ts
+var UNSAFE_PROTOCOL = /^\s*(javascript|data|vbscript|blob):/i;
+var PROTOCOL_RELATIVE = /^\s*\/\//;
+function normalizeForCheck(url) {
+  return url.trim().replace(/\\/g, "/");
+}
+function sanitizeNavigationUrl(url) {
+  if (!url) return void 0;
+  const trimmed = url.trim();
+  if (!trimmed) return void 0;
+  const normalized = normalizeForCheck(trimmed);
+  if (UNSAFE_PROTOCOL.test(normalized)) return void 0;
+  if (PROTOCOL_RELATIVE.test(normalized)) return void 0;
+  return trimmed;
+}
+function isSafeRedirectPath(url) {
+  const normalized = normalizeForCheck(url);
+  if (!normalized.startsWith("/")) return false;
+  if (PROTOCOL_RELATIVE.test(normalized)) return false;
+  if (UNSAFE_PROTOCOL.test(normalized)) return false;
+  return true;
+}
+
 // src/index.ts
 function classifyHttpError(status, message) {
   const defaultMessage = message ?? "An unexpected error occurred";
@@ -313,6 +403,8 @@ function createEventEmitter() {
 var LAROSE_VERSION = "0.1.0";
 export {
   LAROSE_VERSION,
+  SPRING_PRESETS,
+  animateSpringToTarget,
   classifyHttpError,
   createAsyncStateMachine,
   createCompositeFeatureFlagEvaluator,
@@ -323,8 +415,16 @@ export {
   createSessionStateMachine,
   createStaticFeatureFlagEvaluator,
   detectA11yPreferences,
+  getSpringPreset,
+  isSafeRedirectPath,
+  isSpringSettled,
+  motionDuration,
   resetDeprecationWarnings,
+  resolveReducedMotion,
   resolveUIState,
+  sanitizeNavigationUrl,
+  springResponseTime,
+  stepSpring,
   subscribeA11yPreferences,
   warnDeprecation
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@larose-ui/core",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Core types, state machines, and utilities for laRose UI platform",
   "type": "module",
   "main": "./dist/index.js",