@larose-ui/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 laRose contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Log a one-time deprecation warning in non-production environments.
+ */
+declare function warnDeprecation(id: string, message: string, replacement?: string): void;
+/** Reset warned set — for tests only. */
+declare function resetDeprecationWarnings(): void;
+
+type SessionState = 'authenticated' | 'unauthenticated' | 'refreshing' | 'expired' | 'revoked' | 'unauthorized';
+interface UserContext {
+    id: string;
+    name?: string;
+    email?: string;
+    roles?: string[];
+    attributes?: Record<string, unknown>;
+}
+interface TenantContext {
+    id: string;
+    name?: string;
+    locale?: string;
+    timezone?: string;
+    theme?: ThemeMode;
+    /** Named preset from @larose-ui/themes (e.g. ocean, forest) */
+    themePreset?: string;
+    brandColors?: Record<string, string>;
+    permissions?: string[];
+    features?: Record<string, boolean | 'loading'>;
+}
+interface FeatureFlagResult {
+    enabled: boolean;
+    loading: boolean;
+    reason?: string;
+    variant?: string;
+}
+interface A11yPreferences {
+    reducedMotion: boolean;
+    highContrast: boolean;
+}
+interface VersionMatrix {
+    frontend: string;
+    api?: string;
+    feature?: string;
+    compatible: boolean;
+    warnings: string[];
+}
+interface NetworkSnapshot {
+    condition: NetworkCondition;
+    online: boolean;
+    effectiveType?: string;
+    rtt?: number;
+}
+interface PermissionSnapshot {
+    granted: string[];
+    loading: boolean;
+}
+interface FeatureFlagSnapshot {
+    flags: Record<string, FeatureFlagResult>;
+    loading: boolean;
+}
+interface OfflineSnapshot {
+    status: string;
+    queueLength: number;
+}
+interface LocaleSnapshot {
+    locale: string;
+    dir: 'ltr' | 'rtl';
+}
+interface ThemeSnapshot {
+    mode: ThemeMode;
+    density: Density;
+    tenantId?: string;
+}
+/**
+ * Unified read-only snapshot of the laRose frontend operating environment.
+ * Consumed by DevTools, observability correlators, and application diagnostics.
+ */
+interface LaRoseRuntimeContext {
+    environment: Environment;
+    tenant: TenantContext | null;
+    user: UserContext | null;
+    session: SessionState;
+    permissions: PermissionSnapshot;
+    features: FeatureFlagSnapshot;
+    network: NetworkSnapshot;
+    offline: OfflineSnapshot;
+    locale: LocaleSnapshot;
+    timezone: string;
+    theme: ThemeSnapshot;
+    accessibility: A11yPreferences;
+    version: VersionMatrix;
+}
+declare function createDefaultRuntimeContext(overrides?: Partial<LaRoseRuntimeContext>): LaRoseRuntimeContext;
+
+type RuntimeEventType = 'runtime.mounted' | 'runtime.updated' | 'runtime.tenant.changed' | 'session.transition' | 'network.transition' | 'permission.checked' | 'feature.evaluated' | 'offline.transition' | 'environment.changed' | 'api.request' | 'api.response' | 'error' | 'component.mounted' | 'component.rendered' | 'user.interaction';
+interface RuntimeEvent<T extends Record<string, unknown> = Record<string, unknown>> {
+    type: RuntimeEventType;
+    timestamp: number;
+    component?: string;
+    metadata?: T;
+}
+interface RuntimeEventBus {
+    emit(event: Omit<RuntimeEvent, 'timestamp'> & {
+        timestamp?: number;
+    }): RuntimeEvent;
+    subscribe(listener: (event: RuntimeEvent) => void): () => void;
+    getTimeline(limit?: number): RuntimeEvent[];
+    clear(): void;
+}
+interface RuntimeEventBusOptions {
+    maxEvents?: number;
+}
+declare function createRuntimeEventBus(options?: RuntimeEventBusOptions): RuntimeEventBus;
+
+type SessionEvent = {
+    type: 'AUTHENTICATE';
+} | {
+    type: 'REFRESH';
+} | {
+    type: 'REFRESH_SUCCESS';
+} | {
+    type: 'REFRESH_FAILED';
+} | {
+    type: 'EXPIRE';
+} | {
+    type: 'REVOKE';
+} | {
+    type: 'UNAUTHORIZE';
+} | {
+    type: 'SIGN_OUT';
+};
+interface SessionStateMachine {
+    state: SessionState;
+    send: (event: SessionEvent) => SessionState;
+    reset: () => void;
+}
+declare function createSessionStateMachine(initial?: SessionState): SessionStateMachine;
+
+interface FeatureFlagEvaluationContext {
+    userId?: string;
+    tenantId?: string;
+    organizationId?: string;
+    environment?: Environment;
+    attributes?: Record<string, unknown>;
+}
+interface FeatureFlagEvaluator {
+    evaluate(name: string, context: FeatureFlagEvaluationContext): FeatureFlagResult;
+}
+type StaticFeatureFlagValue = boolean | 'loading';
+interface PercentageRolloutConfig {
+    enabled: boolean;
+    percentage?: number;
+    loading?: boolean;
+}
+declare function createStaticFeatureFlagEvaluator(flags: Record<string, StaticFeatureFlagValue>, loading?: boolean): FeatureFlagEvaluator;
+declare function createPercentageRolloutEvaluator(config: Record<string, PercentageRolloutConfig>): FeatureFlagEvaluator;
+declare function createCompositeFeatureFlagEvaluator(evaluators: FeatureFlagEvaluator[]): FeatureFlagEvaluator;
+
+declare function detectA11yPreferences(): A11yPreferences;
+declare function subscribeA11yPreferences(onChange: (preferences: A11yPreferences) => void): () => void;
+
+/**
+ * UI component lifecycle states supported across laRose.
+ */
+type UIState = 'idle' | 'loading' | 'success' | 'error' | 'empty' | 'disabled' | 'readonly' | 'unauthorized' | 'offline' | 'retrying';
+/**
+ * Async operation states for state-machine driven components.
+ */
+type AsyncState = 'idle' | 'loading' | 'submitting' | 'success' | 'error' | 'retrying';
+type Density = 'compact' | 'comfortable' | 'spacious';
+type ThemeMode = 'light' | 'dark';
+type Environment = 'development' | 'staging' | 'production' | 'demo' | 'readonly' | 'maintenance';
+type NetworkCondition = 'online' | 'fast' | 'offline' | 'slow' | 'intermittent' | 'high-latency' | 'failed' | 'recovering';
+type PermissionFallback = 'visible' | 'hidden' | 'disabled' | 'readonly' | 'forbidden' | 'loading';
+type HttpErrorCode = 401 | 403 | 404 | 409 | 422 | 429 | 500 | 503;
+interface ApiError {
+    code: HttpErrorCode | number;
+    message: string;
+    details?: Record<string, unknown>;
+    retryable: boolean;
+}
+interface AsyncStateMachine<TData = unknown, TError = ApiError> {
+    state: AsyncState;
+    data: TData | null;
+    error: TError | null;
+    retryCount: number;
+    send: (event: AsyncEvent) => void;
+    reset: () => void;
+}
+type AsyncEvent = {
+    type: 'START';
+} | {
+    type: 'SUBMIT';
+} | {
+    type: 'SUCCESS';
+    data?: unknown;
+} | {
+    type: 'ERROR';
+    error?: unknown;
+} | {
+    type: 'RETRY';
+} | {
+    type: 'RESET';
+};
+interface Permission {
+    action: string;
+    resource?: string;
+    allowed: boolean;
+    reason?: string;
+}
+interface VersionInfo {
+    frontend: string;
+    backend?: string;
+    compatible: boolean;
+    warnings: string[];
+}
+type Variant = 'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive';
+type Size = 'sm' | 'md' | 'lg';
+interface ComponentStateProps {
+    state?: UIState;
+    loading?: boolean;
+    error?: string | ApiError | null;
+    disabled?: boolean;
+    readonly?: boolean;
+}
+declare function classifyHttpError(status: number, message?: string): ApiError;
+declare function createAsyncStateMachine<TData = unknown, TError = ApiError>(initialState?: AsyncState): AsyncStateMachine<TData, TError>;
+declare function resolveUIState(props: ComponentStateProps): UIState;
+declare function createEventEmitter<T extends Record<string, unknown>>(): {
+    on<K extends keyof T>(event: K, listener: (payload: T[K]) => void): () => boolean | undefined;
+    emit<K extends keyof T>(event: K, payload: T[K]): void;
+};
+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 };

package/dist/index.js

@@ -0,0 +1,330 @@
+// src/deprecation.ts
+var warned = /* @__PURE__ */ new Set();
+function warnDeprecation(id, message, replacement) {
+  const isProd = typeof process !== "undefined" && process.env.NODE_ENV === "production";
+  if (isProd || warned.has(id)) return;
+  warned.add(id);
+  const suffix = replacement ? ` Use ${replacement} instead.` : "";
+  console.warn(`[laRose] Deprecated (${id}): ${message}.${suffix}`);
+}
+function resetDeprecationWarnings() {
+  warned.clear();
+}
+
+// src/runtime/types.ts
+function createDefaultRuntimeContext(overrides = {}) {
+  return {
+    environment: "development",
+    tenant: null,
+    user: null,
+    session: "unauthenticated",
+    permissions: { granted: [], loading: false },
+    features: { flags: {}, loading: false },
+    network: { condition: "fast", online: true },
+    offline: { status: "idle", queueLength: 0 },
+    locale: { locale: "en", dir: "ltr" },
+    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    theme: { mode: "light", density: "comfortable" },
+    accessibility: { reducedMotion: false, highContrast: false },
+    version: {
+      frontend: "0.1.0",
+      compatible: true,
+      warnings: []
+    },
+    ...overrides
+  };
+}
+
+// src/runtime/eventBus.ts
+function createRuntimeEventBus(options = {}) {
+  const maxEvents = options.maxEvents ?? 500;
+  const timeline = [];
+  const listeners = /* @__PURE__ */ new Set();
+  return {
+    emit(event) {
+      const full = {
+        ...event,
+        timestamp: event.timestamp ?? Date.now()
+      };
+      timeline.push(full);
+      if (timeline.length > maxEvents) {
+        timeline.shift();
+      }
+      listeners.forEach((listener) => listener(full));
+      return full;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    getTimeline(limit) {
+      if (limit === void 0) return [...timeline];
+      return timeline.slice(-limit);
+    },
+    clear() {
+      timeline.length = 0;
+    }
+  };
+}
+
+// src/runtime/session.ts
+function createSessionStateMachine(initial = "unauthenticated") {
+  let state = initial;
+  const machine = {
+    get state() {
+      return state;
+    },
+    send(event) {
+      switch (event.type) {
+        case "AUTHENTICATE":
+          state = "authenticated";
+          break;
+        case "REFRESH":
+          if (state === "authenticated" || state === "expired") {
+            state = "refreshing";
+          }
+          break;
+        case "REFRESH_SUCCESS":
+          state = "authenticated";
+          break;
+        case "REFRESH_FAILED":
+          state = state === "refreshing" ? "expired" : state;
+          break;
+        case "EXPIRE":
+          state = "expired";
+          break;
+        case "REVOKE":
+          state = "revoked";
+          break;
+        case "UNAUTHORIZE":
+          state = "unauthorized";
+          break;
+        case "SIGN_OUT":
+          state = "unauthenticated";
+          break;
+      }
+      return state;
+    },
+    reset() {
+      state = initial;
+    }
+  };
+  return machine;
+}
+
+// src/runtime/featureFlags.ts
+function hashToPercent(input) {
+  let hash = 0;
+  for (let i = 0; i < input.length; i++) {
+    hash = (hash << 5) - hash + input.charCodeAt(i);
+    hash |= 0;
+  }
+  return Math.abs(hash) % 100;
+}
+function createStaticFeatureFlagEvaluator(flags, loading = false) {
+  return {
+    evaluate(name) {
+      const value = flags[name];
+      if (value === "loading" || loading) {
+        return { enabled: false, loading: true };
+      }
+      if (value === true) {
+        return { enabled: true, loading: false };
+      }
+      return {
+        enabled: false,
+        loading: false,
+        reason: value === false ? "disabled" : "unknown flag"
+      };
+    }
+  };
+}
+function createPercentageRolloutEvaluator(config) {
+  return {
+    evaluate(name, context) {
+      const entry = config[name];
+      if (!entry) {
+        return { enabled: false, loading: false, reason: "unknown flag" };
+      }
+      if (entry.loading) {
+        return { enabled: false, loading: true };
+      }
+      if (!entry.enabled) {
+        return { enabled: false, loading: false, reason: "disabled" };
+      }
+      const percentage = entry.percentage ?? 100;
+      if (percentage >= 100) {
+        return { enabled: true, loading: false };
+      }
+      if (percentage <= 0) {
+        return { enabled: false, loading: false, reason: "rollout 0%" };
+      }
+      const bucketKey = `${context.userId ?? "anonymous"}:${context.tenantId ?? "default"}:${name}`;
+      const bucket = hashToPercent(bucketKey);
+      const enabled = bucket < percentage;
+      return {
+        enabled,
+        loading: false,
+        reason: enabled ? void 0 : `rollout ${percentage}%`,
+        variant: enabled ? "treatment" : "control"
+      };
+    }
+  };
+}
+function createCompositeFeatureFlagEvaluator(evaluators) {
+  return {
+    evaluate(name, context) {
+      for (const evaluator of evaluators) {
+        const result = evaluator.evaluate(name, context);
+        if (result.loading || result.enabled || result.reason !== "unknown flag") {
+          return result;
+        }
+      }
+      return { enabled: false, loading: false, reason: "unknown flag" };
+    }
+  };
+}
+
+// src/runtime/a11y.ts
+function detectA11yPreferences() {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return { reducedMotion: false, highContrast: false };
+  }
+  const reducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  const highContrast = window.matchMedia("(prefers-contrast: more)").matches;
+  return { reducedMotion, highContrast };
+}
+function subscribeA11yPreferences(onChange) {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return () => {
+    };
+  }
+  const motionQuery = window.matchMedia("(prefers-reduced-motion: reduce)");
+  const contrastQuery = window.matchMedia("(prefers-contrast: more)");
+  const notify = () => onChange(detectA11yPreferences());
+  motionQuery.addEventListener("change", notify);
+  contrastQuery.addEventListener("change", notify);
+  return () => {
+    motionQuery.removeEventListener("change", notify);
+    contrastQuery.removeEventListener("change", notify);
+  };
+}
+
+// src/index.ts
+function classifyHttpError(status, message) {
+  const defaultMessage = message ?? "An unexpected error occurred";
+  const retryable = status === 429 || status === 500 || status === 503;
+  const messages = {
+    401: "You are not authenticated. Please sign in.",
+    403: "You don't have permission to perform this action.",
+    404: "The requested resource was not found.",
+    409: "A conflict was detected. The resource may have been modified.",
+    422: "Validation failed. Please check your input.",
+    429: "Too many requests. Please wait before retrying.",
+    500: "A server error occurred. Please try again.",
+    503: "Service temporarily unavailable. Please try again."
+  };
+  const code = status;
+  return {
+    code: status,
+    message: messages[code] ?? defaultMessage,
+    retryable
+  };
+}
+function createAsyncStateMachine(initialState = "idle") {
+  let state = initialState;
+  let data = null;
+  let error = null;
+  let retryCount = 0;
+  const listeners = /* @__PURE__ */ new Set();
+  const notify = () => listeners.forEach((l) => l());
+  const machine = {
+    get state() {
+      return state;
+    },
+    get data() {
+      return data;
+    },
+    get error() {
+      return error;
+    },
+    get retryCount() {
+      return retryCount;
+    },
+    send(event) {
+      switch (event.type) {
+        case "START":
+          state = "loading";
+          error = null;
+          break;
+        case "SUBMIT":
+          state = "submitting";
+          error = null;
+          break;
+        case "SUCCESS":
+          state = "success";
+          data = event.data ?? data;
+          error = null;
+          break;
+        case "ERROR":
+          state = "error";
+          error = event.error ?? error;
+          break;
+        case "RETRY":
+          retryCount += 1;
+          state = "retrying";
+          break;
+        case "RESET":
+          state = "idle";
+          data = null;
+          error = null;
+          retryCount = 0;
+          break;
+      }
+      notify();
+    },
+    reset() {
+      machine.send({ type: "RESET" });
+    }
+  };
+  return machine;
+}
+function resolveUIState(props) {
+  if (props.state) return props.state;
+  if (props.disabled) return "disabled";
+  if (props.readonly) return "readonly";
+  if (props.loading) return "loading";
+  if (props.error) return "error";
+  return "idle";
+}
+function createEventEmitter() {
+  const listeners = /* @__PURE__ */ new Map();
+  return {
+    on(event, listener) {
+      if (!listeners.has(event)) listeners.set(event, /* @__PURE__ */ new Set());
+      listeners.get(event).add(listener);
+      return () => listeners.get(event)?.delete(listener);
+    },
+    emit(event, payload) {
+      listeners.get(event)?.forEach((l) => l(payload));
+    }
+  };
+}
+var LAROSE_VERSION = "0.1.0";
+export {
+  LAROSE_VERSION,
+  classifyHttpError,
+  createAsyncStateMachine,
+  createCompositeFeatureFlagEvaluator,
+  createDefaultRuntimeContext,
+  createEventEmitter,
+  createPercentageRolloutEvaluator,
+  createRuntimeEventBus,
+  createSessionStateMachine,
+  createStaticFeatureFlagEvaluator,
+  detectA11yPreferences,
+  resetDeprecationWarnings,
+  resolveUIState,
+  subscribeA11yPreferences,
+  warnDeprecation
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@larose-ui/core",
+  "version": "0.1.0",
+  "description": "Core types, state machines, and utilities for laRose UI platform",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/larose-ui/larose.git",
+    "directory": "packages/core"
+  },
+  "keywords": [
+    "larose",
+    "react",
+    "ui-platform",
+    "design-system",
+    "saas"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}