kosmio 0.1.0

package/types/core.d.ts

@@ -0,0 +1,210 @@
+import type { CSSProperties, KeyboardEvent } from "react";
+import type { QueryClient } from "@tanstack/react-query";
+
+export function cx(...classes: Array<string | false | null | undefined>): string;
+
+export function clamp(value: number, min: number, max: number): number;
+
+export function createStaggerDelay(
+  index: number,
+  stepMs?: number,
+  maxDelayMs?: number
+): string;
+
+export function getRevealStyle(
+  index?: number,
+  stepMs?: number,
+  maxDelayMs?: number
+): CSSProperties;
+
+export const motion: {
+  duration: Record<string, number>;
+  ease: Record<string, number[]>;
+  stagger: Record<string, number>;
+  transition: Record<string, (overrides?: Record<string, unknown>) => Record<string, unknown>>;
+  appear: Record<string, Record<string, unknown>>;
+  css: {
+    ms(duration: string | number): string;
+    bezier(easeName: string): string;
+    transition(options?: {
+      props?: string[];
+      dur?: string | number;
+      ease?: string;
+      delay?: string | number;
+    }): string;
+  };
+};
+export function rowAppearStyle(options?: { index?: number; preset?: Record<string, unknown> }): CSSProperties;
+export const variants: Record<string, Record<string, unknown>>;
+
+export function isEditableTarget(target: EventTarget | null): boolean;
+export const isTypingTarget: typeof isEditableTarget;
+export function normalizeShortcutKey(key?: string): string;
+export function parseShortcutKeys(shortcut: unknown): string[];
+export function shortcutMatches(event: KeyboardEvent | globalThis.KeyboardEvent, shortcut: unknown): boolean;
+
+export function createShortcutMatcher(
+  shortcut: string
+): (event: KeyboardEvent | globalThis.KeyboardEvent) => boolean;
+
+export function toPascalCase(value: unknown): string;
+export function toSnake(value: string): string;
+export function toCamel(value: string): string;
+export function keysToCamel<T = unknown>(obj: T): T;
+export function keysToSnake<T = unknown>(obj: T): T;
+
+export type RouteParams = Record<string, string | number | boolean | null | undefined>;
+export type LocalizedRoutes = Record<string, Record<string, string>>;
+
+export interface LocalizedRouteMatch {
+  language: string;
+  lang: string;
+  routeKey: string;
+  pattern: string;
+  params: Record<string, string>;
+  ambiguous: boolean;
+}
+
+export interface LocalizedRouterOptions {
+  routes?: LocalizedRoutes;
+  defaultLanguage?: string;
+  supportedLanguages?: string[];
+  mobileNavRouteKeys?: Iterable<string>;
+}
+
+export interface LocalizedRouter {
+  routes: LocalizedRoutes;
+  supportedLanguages: string[];
+  defaultLanguage: string;
+  normalizeLanguage(language?: string): string;
+  getLocaleRoutes(language?: string): Record<string, string>;
+  getRoutePattern(language: string, routeKey: string): string | null;
+  buildRoutePath(routePattern?: string | null, params?: RouteParams): string;
+  getRoutePath(language: string, routeKey: string, params?: RouteParams): string;
+  getRoutePaths(routeKey: string): string[];
+  getRouteRedirects(routeKey: string, targetRouteKey: string): Array<{
+    language: string;
+    path: string;
+    redirect: string;
+  }>;
+  matchLocalizedRoute(pathname: string): LocalizedRouteMatch | null;
+  translateRoutePath(pathname: string, nextLanguage: string): string | null;
+  shouldRenderMobileNav(pathname: string): boolean;
+  isRouteKeyActive(pathname: string, routeKey: string): boolean;
+}
+
+export function buildRoutePath(routePattern?: string | null, params?: RouteParams): string;
+export function createLocalizedRouter(options?: LocalizedRouterOptions): LocalizedRouter;
+
+export interface FieldConfig {
+  name?: string;
+  type?: string | string[] | { name?: string; values?: unknown[] };
+  required?: boolean;
+  post?: boolean;
+  edit?: boolean;
+  formGrouping?: unknown;
+  default?: unknown;
+  enum?: unknown[];
+  [key: string]: unknown;
+}
+
+export const FieldTypes: Readonly<Record<string, string>>;
+export function Field(config?: FieldConfig): Readonly<FieldConfig>;
+export function createEnumType(name: string, values: unknown[]): Readonly<{ kind: string; name: string | null; values: unknown[] }>;
+export function isEnumType(value: unknown): boolean;
+export function resolveTypeDescriptor(rawType?: unknown, explicitEnum?: unknown[]): {
+  type: string;
+  enum: unknown[] | null;
+  enumTypeName: string | null;
+};
+
+export class Entity {
+  constructor(data?: Record<string, unknown>);
+  toJSON(): Record<string, unknown>;
+}
+
+export class EntityModelFactory {
+  static build(config: EntityResourceConfig): Record<string, unknown>;
+}
+
+export function createEntityModels(config: EntityResourceConfig): Record<string, unknown>;
+export function createEntityResource(config: EntityResourceConfig): Record<string, unknown>;
+
+export interface EntityResourceConfig {
+  name: string;
+  plural?: string;
+  editable?: boolean;
+  fields?: Record<string, FieldConfig> | FieldConfig[];
+  elements?: Record<string, FieldConfig> | FieldConfig[];
+  picture?: unknown;
+  crud?: CrudConfig;
+  [key: string]: unknown;
+}
+
+export interface CrudConfig {
+  client?: ApiClient;
+  basePath?: string;
+  resource?: string;
+  makeKeys?: unknown;
+  asOptions?: boolean;
+  listAdapter?: (value: unknown) => unknown;
+  detailAdapter?: (value: unknown) => unknown;
+  updateMethod?: "PUT" | "PATCH";
+}
+
+export interface EndpointConfig {
+  method: string;
+  path: string | ((pathParams?: Record<string, unknown>) => string);
+  requestMapper?: (data: unknown) => unknown;
+  responseMapper?: (data: unknown) => unknown;
+  offlineQueue?: boolean;
+}
+
+export class ApiClient {
+  ax: { request(config: Record<string, unknown>): Promise<{ data: unknown }>; defaults?: Record<string, unknown> };
+  queueKey: string;
+  constructor(baseURL?: string, config?: Record<string, unknown>);
+  call(endpoint: EndpointConfig, options?: { pathParams?: Record<string, unknown>; data?: unknown; config?: Record<string, unknown> }): Promise<unknown>;
+}
+
+export function makeQueryHook(client: ApiClient, endpoint: EndpointConfig, makeKey: (...args: unknown[]) => unknown[]): (...args: unknown[]) => unknown;
+export function makeMutationHook(client: ApiClient, endpoint: EndpointConfig, options?: { afterSuccess?: (...args: unknown[]) => void }): () => unknown;
+export function makeCrudHooks(config: {
+  client: ApiClient;
+  basePath: string;
+  resource?: string;
+  mapOne?: (value: unknown) => unknown;
+  mapMany?: (value: unknown) => unknown[];
+  updateMethod?: "PUT" | "PATCH";
+  makeKeys?: unknown;
+  asOptions?: boolean;
+  listAdapter?: (value: unknown) => unknown;
+  detailAdapter?: (value: unknown) => unknown;
+}): Record<string, unknown>;
+
+export function createKosmioQueryClient(options?: ConstructorParameters<typeof QueryClient>[0]): QueryClient;
+export const queryClient: QueryClient;
+
+export function configureOfflineWriteQueue(options?: {
+  storagePrefix?: string;
+  resolveScopeKey?: () => string | Promise<string>;
+  invalidateQueries?: () => unknown;
+  appStateAdapter?: { addListener?: (event: string, listener: (state: unknown) => void) => unknown };
+}): void;
+export function registerOfflineWriteClient<T>(client: T): T;
+export function isOfflineQueueHandledResult(result: unknown): boolean;
+export function isOfflineQueueQueuedResult(result: unknown): boolean;
+export function isOfflineQueueCanceledResult(result: unknown): boolean;
+export function isQueueableWriteRequest(requestConfig: unknown): boolean;
+export function getOfflineWriteQueueScopeKey(input?: { userId?: string; tenantId?: string }): string;
+export function getOfflineWriteQueueState(scopeKey?: string): {
+  isOnline: boolean;
+  isSyncing: boolean;
+  pendingSyncCount: number;
+  hasPendingSync: boolean;
+};
+export function subscribeOfflineWriteQueue(listener: () => void): () => void;
+export function enqueueOfflineWrite(client: ApiClient, requestConfig: Record<string, unknown>, reason?: string): Promise<Record<string, unknown>>;
+export function shouldQueueOfflineWrite(error: unknown, requestConfig: unknown): boolean;
+export function requestOfflineWriteQueueSync(): void;
+export function startOfflineWriteQueueSync(): undefined;

package/types/global.d.ts

@@ -0,0 +1 @@
+declare module "*.css";

package/types/i18n.d.ts

@@ -0,0 +1,79 @@
+import type { ReactNode } from "react";
+
+export interface DetectInitialLanguageOptions {
+  defaultLanguage: string;
+  storageKey?: string;
+  router?: LocalizedRouterContract;
+  normalizeLanguage?: (language?: string | null) => string;
+  matchRoute?: (pathname: string) => { lang?: string; ambiguous?: boolean } | null;
+  pathname?: string;
+  navigatorLanguage?: string;
+}
+
+export interface LocalizedRouterContract {
+  normalizeLanguage?: (language?: string | null) => string;
+  matchLocalizedRoute?: (pathname: string) => { lang?: string; ambiguous?: boolean } | null;
+  translateRoutePath?: (pathname: string, nextLanguage: string) => string | null;
+}
+
+export function detectInitialLanguage(options: DetectInitialLanguageOptions): string;
+
+export interface CreateI18nOptions {
+  instance?: {
+    use(plugin: unknown): CreateI18nOptions["instance"];
+    init(options: Record<string, unknown>): unknown;
+  };
+  resources: Record<string, unknown>;
+  defaultLanguage: string;
+  supportedLanguages?: string[];
+  storageKey?: string;
+  router?: LocalizedRouterContract;
+  normalizeLanguage?: (language?: string | null) => string;
+  matchRoute?: (pathname: string) => { lang?: string; ambiguous?: boolean } | null;
+  initReact?: boolean;
+  options?: Record<string, unknown>;
+}
+
+export function createI18n<T = unknown>(options: CreateI18nOptions): T;
+
+export interface LanguageProviderProps {
+  children?: ReactNode;
+  defaultLanguage: string;
+  storageKey?: string;
+  router?: LocalizedRouterContract;
+  normalizeLanguage?: (language?: string | null) => string;
+  translateRoutePath?: (pathname: string, nextLanguage: string) => string | null;
+  matchRoute?: (pathname: string) => { lang?: string; ambiguous?: boolean } | null;
+  getPreferredLanguage?: () => string | null | undefined;
+  onLanguageChange?: (language: string) => void | Promise<void>;
+}
+
+export interface LanguageContextValue {
+  lang: string;
+  changeLanguage: (language: string) => Promise<void>;
+}
+
+export function LanguageProvider(props: LanguageProviderProps): import("react").JSX.Element;
+export function useLanguage(): LanguageContextValue;
+
+export type EnumOptionValue = string | number;
+
+export interface I18nEnumOptionDefinition {
+  value: EnumOptionValue;
+  label?: ReactNode;
+  labelKey?: string;
+  icon?: unknown;
+  iconName?: unknown;
+  [key: string]: unknown;
+}
+
+export interface UseEnumOptionsOptions {
+  includeIcon?: boolean;
+}
+
+export function useEnumLabel(prefix: string): (value?: EnumOptionValue | null, fallback?: string) => string;
+export function useEnumOptions(
+  definitions?: Array<I18nEnumOptionDefinition | EnumOptionValue>,
+  baseKey?: string,
+  options?: UseEnumOptionsOptions
+): I18nEnumOptionDefinition[];

package/types/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./core.js";
+export * from "./context.js";
+export * from "./i18n.js";
+export * from "./app.js";
+export * from "./permissions.js";
+export * from "./platform.js";
+export * from "./theme.js";
+export * from "./ui.js";

package/types/permissions.d.ts

@@ -0,0 +1,61 @@
+export type PermissionLevelMap = Record<string, number>;
+export type PlanLimitValue = number | typeof Infinity;
+export type PlanLimits = Record<string, Record<string, PlanLimitValue>>;
+export interface PermissionLimitRule {
+  usageKey?: string;
+  limitKey?: string;
+  byPlan?: Record<string, PlanLimitValue>;
+  plans?: Record<string, PlanLimitValue>;
+}
+export type PermissionLimitChecks = Record<string, true | string | PermissionLimitRule | false | null | undefined>;
+
+export interface AccessRule {
+  allow?: boolean;
+  minRole?: string;
+  minPlan?: string;
+  limit?: PermissionLimitRule;
+  limits?: PermissionLimitChecks;
+  [key: string]: unknown;
+}
+
+export type PermissionTree = {
+  [key: string]: AccessRule | PermissionTree;
+};
+
+export interface PermissionContext {
+  role?: string;
+  plan?: string;
+  usage?: Record<string, number>;
+}
+
+export interface PermissionSystemOptions {
+  roles?: PermissionLevelMap;
+  plans?: PermissionLevelMap;
+  planLimits?: PlanLimits;
+  permissions?: PermissionTree;
+  defaults?: PermissionContext;
+}
+
+export interface PermissionSystem {
+  roles: PermissionLevelMap;
+  plans: PermissionLevelMap;
+  planLimits: PlanLimits;
+  permissions: PermissionTree;
+  canAccess(rule?: AccessRule | null, context?: PermissionContext): boolean;
+  getRoleLevel(role?: string): number;
+  getPlanLevel(plan?: string): number;
+  resolvePermissions(context?: PermissionContext): unknown;
+  usePermissions(role?: string, plan?: string, usage?: Record<string, number>): unknown;
+}
+
+export function createAccessRule(rule?: AccessRule): Readonly<AccessRule>;
+export function limitByPlan(
+  usageKey: string,
+  byPlan: Record<string, PlanLimitValue>,
+  options?: { limitKey?: string }
+): Readonly<Required<Pick<PermissionLimitRule, "usageKey" | "limitKey" | "byPlan">>>;
+export function createPermissionRules<T extends PermissionTree>(rules?: T): Readonly<T>;
+export function createPermissionScope<T extends PermissionTree>(path: string | string[], rules?: T): Readonly<PermissionTree>;
+export function mergePermissionRules(...rules: PermissionTree[]): Readonly<PermissionTree>;
+export function createPlanLimits<T extends PlanLimits>(planLimits?: T): Readonly<T>;
+export function createPermissionSystem(options?: PermissionSystemOptions): PermissionSystem;

package/types/platform.d.ts

@@ -0,0 +1,71 @@
+import type { ReactNode } from "react";
+export { NativeBackButtonHandler } from "./ui.js";
+
+export interface CapacitorRuntimeAdapter {
+  isNativePlatform?: () => boolean;
+  getPlatform?: () => string;
+}
+
+export interface PlatformRuntimeOptions {
+  capacitor?: CapacitorRuntimeAdapter;
+  androidAppScheme?: string;
+  authCallbackPath?: string;
+  nativeAuthHost?: string;
+  nativeAuthPath?: string;
+}
+
+export interface PlatformRuntime {
+  isNativeApp: () => boolean;
+  getNativePlatform: () => string;
+  getAuthCallbackPath: () => string;
+  getNativeAuthCallbackUrl: () => string;
+  getAuthCallbackUrl: () => string;
+  isGoogleAuthAvailable: () => boolean;
+}
+
+export function createPlatformRuntime(options?: PlatformRuntimeOptions): PlatformRuntime;
+export function mapAppUrlToRoute(url: string): string | null;
+
+export interface SystemBarsPlugin {
+  setTheme?: (theme: {
+    navigationBarColor?: string;
+    statusBarColor?: string;
+    lightNavigationBar?: boolean;
+    lightStatusBar?: boolean;
+  }) => Promise<void> | void;
+  markAppReady?: () => Promise<void> | void;
+}
+
+export interface SystemBarsControllerOptions {
+  registerPlugin?: (pluginName: string) => SystemBarsPlugin;
+  isNative?: boolean;
+  pluginName?: string;
+  pluginKey?: string;
+  statusBarColors?: Record<"light" | "dark", string>;
+  navigationBarColors?: Record<"light" | "dark", string>;
+}
+
+export interface SystemBarsController {
+  getSystemBarsPlugin: () => SystemBarsPlugin | null;
+  syncSystemBarsTheme: (theme: string) => Promise<void>;
+  markNativeAppReady: () => Promise<void>;
+}
+
+export const DEFAULT_THEME_STATUS_BAR_COLORS: Readonly<Record<"light" | "dark", string>>;
+export const DEFAULT_THEME_NAVIGATION_BAR_COLORS: Readonly<Record<"light" | "dark", string>>;
+export function createSystemBarsController(options?: SystemBarsControllerOptions): SystemBarsController;
+
+export interface AppUrlListenerProps {
+  app?: {
+    getLaunchUrl?: () => Promise<{ url?: string | null } | null>;
+    addListener?: (
+      eventName: "appUrlOpen",
+      listenerFunc: (event: { url?: string | null }) => void
+    ) => Promise<{ remove?: () => void | Promise<void> }>;
+  };
+  isNative?: boolean;
+  mapUrlToRoute?: (url?: string | null) => string | null;
+  children?: ReactNode;
+}
+
+export function AppUrlListener(props: AppUrlListenerProps): null;

package/types/theme.d.ts

@@ -0,0 +1,67 @@
+import type { CSSProperties, ElementType, HTMLAttributes, ReactNode } from "react";
+
+export type KosmioThemeMode = "light" | "dark";
+export type KosmioThemeValue = string | number;
+
+export interface KosmioModeValue {
+  value?: KosmioThemeValue;
+  light?: KosmioThemeValue;
+  dark?: KosmioThemeValue;
+}
+
+export type KosmioColorValue = KosmioThemeValue | KosmioModeValue;
+
+export interface KosmioThemeInput {
+  mode?: KosmioThemeMode;
+  colors?: Record<string, KosmioColorValue>;
+  colorAliases?: Partial<Record<KosmioSemanticColorName, string>>;
+  fontSizes?: Record<string, KosmioThemeValue>;
+}
+
+export interface KosmioTheme {
+  mode: KosmioThemeMode;
+  colors: Record<string, KosmioColorValue>;
+  colorAliases: Record<KosmioSemanticColorName, string>;
+  fontSizes: Record<string, KosmioThemeValue>;
+}
+
+export type KosmioSemanticColorName =
+  | "bg"
+  | "surface"
+  | "surfaceMuted"
+  | "surfaceStrong"
+  | "text"
+  | "textMuted"
+  | "primary"
+  | "primaryText"
+  | "tag"
+  | "danger"
+  | "dangerText"
+  | "success"
+  | "border"
+  | "focus";
+
+export const KOSMIO_DEFAULT_THEME: KosmioTheme;
+
+export function createKosmioTheme(theme?: KosmioThemeInput): KosmioTheme;
+
+export function resolveThemeMode(
+  mode?: string,
+  fallbackMode?: KosmioThemeMode
+): KosmioThemeMode;
+
+export function createThemeStyle(
+  theme?: KosmioThemeInput,
+  options?: { mode?: KosmioThemeMode }
+): CSSProperties;
+
+export interface KosmioThemeProviderProps extends HTMLAttributes<HTMLElement> {
+  as?: ElementType;
+  theme?: KosmioThemeInput;
+  mode?: KosmioThemeMode;
+  children?: ReactNode;
+}
+
+export function KosmioThemeProvider(
+  props: KosmioThemeProviderProps
+): import("react").JSX.Element;