@kupola/kupola 1.2.0 → 1.3.1

package/adapters/axios.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Axios adapter for Kupola HTTP client plugin system.
+ */
+
+export interface AxiosAdapterOptions {
+  /** Additional Axios request config to merge into every request */
+  [key: string]: any;
+}
+
+/**
+ * Create a Kupola-compatible HTTP client from an Axios instance.
+ *
+ * @param axiosInstance - An Axios instance (from axios.create() or default axios)
+ * @param options - Additional Axios request config to merge into every request
+ * @returns Kupola HTTP client object with a `fetch` function
+ */
+export function createAxiosAdapter(
+  axiosInstance: any,
+  options?: AxiosAdapterOptions
+): {
+  fetch(url: string, fetchOptions?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+  }): Promise<{
+    ok: boolean;
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    url: string;
+    json(): Promise<any>;
+    text(): Promise<string>;
+  }>;
+};

package/adapters/axios.js

@@ -0,0 +1,122 @@
+/**
+ * Axios adapter for Kupola HTTP client plugin system.
+ * 
+ * Allows using Axios (with interceptors, custom config, etc.) as the HTTP
+ * client for all useDeps() / useQuery() requests.
+ * 
+ * @module adapters/axios
+ * 
+ * @example
+ * import { configureHttpClient } from 'kupola';
+ * import { createAxiosAdapter } from 'kupola/adapters/axios';
+ * import axios from 'axios';
+ * 
+ * const api = axios.create({ baseURL: '/api', timeout: 10000 });
+ * 
+ * // Axios interceptors work as expected
+ * api.interceptors.request.use(config => {
+ *   config.headers.Authorization = `Bearer ${getToken()}`;
+ *   return config;
+ * });
+ * 
+ * configureHttpClient(createAxiosAdapter(api));
+ */
+
+/**
+ * Create a Kupola-compatible HTTP client from an Axios instance.
+ * 
+ * @param {Object} axiosInstance - An Axios instance (from axios.create() or default axios)
+ * @param {Object} [options] - Additional Axios request config to merge into every request
+ * @returns {{ fetch: Function }} Kupola HTTP client object
+ */
+export function createAxiosAdapter(axiosInstance, options = {}) {
+    if (!axiosInstance || typeof axiosInstance.request !== 'function') {
+        throw new TypeError('[Kupola] createAxiosAdapter: invalid Axios instance (must have .request method)');
+    }
+
+    return {
+        /**
+         * Fetch function compatible with Kupola's HTTP client interface.
+         * Translates Fetch API semantics to Axios, and Axios response back to
+         * Fetch API Response shape.
+         * 
+         * @param {string} url - Request URL
+         * @param {Object} [fetchOptions] - Fetch-style options
+         * @param {string} [fetchOptions.method='GET'] - HTTP method
+         * @param {Object} [fetchOptions.headers] - Request headers
+         * @param {string} [fetchOptions.body] - Request body (JSON string)
+         * @returns {Promise<Object>} Response-like object { ok, status, headers, json(), text() }
+         */
+        fetch: async function (url, fetchOptions = {}) {
+            // Build Axios config
+            const axiosConfig = {
+                url,
+                method: (fetchOptions.method || 'GET').toLowerCase(),
+                headers: fetchOptions.headers || {},
+                // Don't throw on non-2xx — let Kupola handle error status
+                validateStatus: () => true,
+                ...options
+            };
+
+            // Parse body if present (Fetch sends body as JSON string)
+            if (fetchOptions.body) {
+                try {
+                    axiosConfig.data = JSON.parse(fetchOptions.body);
+                } catch (_) {
+                    axiosConfig.data = fetchOptions.body;
+                }
+            }
+
+            try {
+                const response = await axiosInstance.request(axiosConfig);
+
+                // Cache the parsed data to avoid re-parsing on multiple .json() calls
+                let _cachedData;
+                let _dataParsed = false;
+
+                return {
+                    ok: response.status >= 200 && response.status < 300,
+                    status: response.status,
+                    statusText: response.statusText || '',
+                    headers: response.headers || {},
+                    url,
+
+                    json() {
+                        if (!_dataParsed) {
+                            _cachedData = response.data;
+                            _dataParsed = true;
+                        }
+                        return Promise.resolve(_cachedData);
+                    },
+
+                    text() {
+                        if (!_dataParsed) {
+                            _cachedData = typeof response.data === 'string'
+                                ? response.data
+                                : JSON.stringify(response.data);
+                            _dataParsed = true;
+                        }
+                        return Promise.resolve(_cachedData);
+                    }
+                };
+            } catch (error) {
+                // Network error or request was blocked
+                return {
+                    ok: false,
+                    status: 0,
+                    statusText: error.message || 'Network Error',
+                    headers: {},
+                    url,
+
+                    json() {
+                        return Promise.resolve({ error: error.message });
+                    },
+
+                    text() {
+                        return Promise.resolve(error.message);
+                    }
+                };
+            }
+        }
+    };
+}

package/adapters/navios-http.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @navios/http adapter for Kupola HTTP client plugin system.
+ * 
+ * @navios/http is a lightweight, fetch-based axios replacement that supports
+ * interceptors, multiple response types, and works with Next.js / RSC.
+ */
+
+/** Additional @navios/http request config fields that can be merged into every request. */
+export interface NaviosAdapterOptions {
+  /** Response type: 'json' | 'text' | 'blob' | 'arrayBuffer' | 'formData' | 'stream' */
+  responseType?: string;
+  /** Custom status validator, e.g. (status) => status < 500 */
+  validateStatus?: (status: number) => boolean;
+  /** Request credentials: 'omit' | 'same-origin' | 'include' */
+  credentials?: string;
+  /** URL search parameters */
+  params?: Record<string, any> | URLSearchParams;
+  /** Allow any other @navios/http requestConfig fields */
+  [key: string]: any;
+}
+
+/** Minimal @navios/http client interface required by the adapter. */
+export interface NaviosHttpClient {
+  request(config: any): Promise<{
+    data: any;
+    status: number;
+    statusText?: string;
+    headers?: Record<string, string>;
+    config?: any;
+  }>;
+  get(url: string, config?: any): Promise<any>;
+  post(url: string, data?: any, config?: any): Promise<any>;
+  put(url: string, data?: any, config?: any): Promise<any>;
+  patch(url: string, data?: any, config?: any): Promise<any>;
+  delete(url: string, config?: any): Promise<any>;
+  head(url: string, config?: any): Promise<any>;
+  options(url: string, config?: any): Promise<any>;
+  defaults: Record<string, any>;
+  interceptors: {
+    request: { use(onFulfilled: Function, onRejected?: Function): number };
+    response: { use(onFulfilled: Function, onRejected?: Function): number };
+  };
+}
+
+/**
+ * Create a Kupola-compatible HTTP client from a @navios/http instance.
+ *
+ * @param naviosClient - A @navios/http client instance (from create() or default import)
+ * @param options - Additional @navios/http request config to merge into every request
+ * @returns Kupola HTTP client object with a `fetch` function
+ */
+export function createNaviosAdapter(
+  naviosClient: NaviosHttpClient,
+  options?: NaviosAdapterOptions
+): {
+  fetch(url: string, fetchOptions?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+  }): Promise<{
+    ok: boolean;
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    url: string;
+    json(): Promise<any>;
+    text(): Promise<string>;
+  }>;
+};
+/**
+ * @navios/http adapter for Kupola HTTP client plugin system.
+ */
+
+export interface NaviosAdapterOptions {
+  /** Additional request config to merge into every request */
+  [key: string]: any;
+}
+
+/**
+ * Create a Kupola-compatible HTTP client from a @navios/http instance.
+ *
+ * @param naviosClient - A @navios/http client instance (from create())
+ * @param options - Additional request config to merge into every request
+ * @returns Kupola HTTP client object with a `fetch` function
+ */
+export function createNaviosAdapter(
+  naviosClient: {
+    request(config: any): Promise<{
+      status: number;
+      statusText?: string;
+      headers?: Record<string, string>;
+      data: any;
+    }>;
+  },
+  options?: NaviosAdapterOptions
+): {
+  fetch(url: string, fetchOptions?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+  }): Promise<{
+    ok: boolean;
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    url: string;
+    json(): Promise<any>;
+    text(): Promise<string>;
+  }>;
+};

package/adapters/navios-http.js

@@ -0,0 +1,151 @@
+/**
+ * @navios/http adapter for Kupola HTTP client plugin system.
+ * 
+ * Allows using @navios/http (with interceptors, custom config, etc.) as the HTTP
+ * client for all useDeps() / useQuery() requests.
+ * 
+ * @navios/http is a lightweight, fetch-based axios replacement that supports
+ * interceptors, multiple response types, and works with Next.js / RSC.
+ * 
+ * @module adapters/navios-http
+ * 
+ * @example
+ * import { configureHttpClient } from 'kupola';
+ * import { createNaviosAdapter } from 'kupola/adapters/navios-http';
+ * import { create } from '@navios/http';
+ * 
+ * const client = create({ baseURL: '/api' });
+ * 
+ * // @navios/http interceptors work as expected
+ * client.interceptors.request.use((config) => {
+ *   config.headers['Authorization'] = `Bearer ${getToken()}`;
+ *   return config;
+ * });
+ * 
+ * configureHttpClient(createNaviosAdapter(client));
+ */
+
+/**
+ * Create a Kupola-compatible HTTP client from a @navios/http instance.
+ * 
+ * Translates Kupola's fetch-style calls into @navios/http requests,
+ * and maps @navios/http responses back to Kupola's standard format:
+ * { ok, status, statusText, headers, url, json(), text() }
+ * 
+ * @param {Object} naviosClient - A @navios/http client instance (from create() or default import)
+ *   Must expose: .request(config), .get(url, config), .post(url, data, config), etc.
+ * @param {Object} [options] - Additional @navios/http request config merged into every request.
+ *   Supports all @navios/http requestConfig fields:
+ *   - responseType {string}: 'json' | 'text' | 'blob' | 'arrayBuffer' | 'formData' | 'stream'
+ *   - validateStatus {Function}: custom status validator, e.g. () => true
+ *   - credentials {string}: 'omit' | 'same-origin' | 'include'
+ *   - params {Object|URLSearchParams}: URL search parameters
+ * @returns {{ fetch: Function }} Kupola HTTP client object
+ */
+export function createNaviosAdapter(naviosClient, options = {}) {
+    if (!naviosClient || typeof naviosClient.request !== 'function') {
+        throw new TypeError('[Kupola] createNaviosAdapter: invalid @navios/http client (must have .request method)');
+    }
+
+    return {
+        /**
+         * Fetch function compatible with Kupola's HTTP client interface.
+         * Translates Fetch API semantics to @navios/http, and response back to
+         * Fetch API Response shape.
+         * 
+         * @param {string} url - Request URL
+         * @param {Object} [fetchOptions] - Fetch-style options
+         * @param {string} [fetchOptions.method='GET'] - HTTP method
+         * @param {Object} [fetchOptions.headers] - Request headers
+         * @param {string} [fetchOptions.body] - Request body (JSON string)
+         * @returns {Promise<Object>} Response-like object { ok, status, headers, json(), text() }
+         */
+        fetch: async function (url, fetchOptions = {}) {
+            const method = (fetchOptions.method || 'GET').toUpperCase();
+
+            // Build request config for @navios/http
+            // Note: @navios/http uses `data` for body (axios-style), not `body` (fetch-style)
+            const requestConfig = {
+                url,
+                method,
+                headers: fetchOptions.headers || {},
+                // Accept all status codes here; Kupola handles ok/status checking itself
+                validateStatus: () => true,
+                ...options
+            };
+
+            // Parse body if present (Fetch sends body as JSON string,
+            // but @navios/http accepts objects directly as `data`)
+            if (fetchOptions.body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+                try {
+                    requestConfig.data = JSON.parse(fetchOptions.body);
+                } catch (_) {
+                    requestConfig.data = fetchOptions.body;
+                }
+            }
+
+            try {
+                const response = await naviosClient.request(requestConfig);
+
+                // Cache the parsed data to avoid re-parsing on multiple .json() calls
+                let _cachedData;
+                let _dataParsed = false;
+
+                return {
+                    ok: response.status >= 200 && response.status < 300,
+                    status: response.status,
+                    statusText: response.statusText || '',
+                    headers: response.headers || {},
+                    url,
+
+                    json() {
+                        if (!_dataParsed) {
+                            _cachedData = response.data;
+                            _dataParsed = true;
+                        }
+                        return Promise.resolve(_cachedData);
+                    },
+
+                    text() {
+                        if (!_dataParsed) {
+                            _cachedData = typeof response.data === 'string'
+                                ? response.data
+                                : JSON.stringify(response.data);
+                            _dataParsed = true;
+                        }
+                        return Promise.resolve(_cachedData);
+                    }
+                };
+            } catch (error) {
+                // Network error or interceptor rejection.
+                // @navios/http error shape: { message, response?: { status, headers, data }, config }
+                const errStatus = (error.response && error.response.status) || 0;
+                const errHeaders = (error.response && error.response.headers) || {};
+
+                return {
+                    ok: false,
+                    status: errStatus,
+                    statusText: error.message || 'Network Error',
+                    headers: errHeaders,
+                    url,
+
+                    json() {
+                        // Try to return structured error data if available
+                        if (error.response && error.response.data !== undefined) {
+                            return Promise.resolve(error.response.data);
+                        }
+                        return Promise.resolve({ error: error.message });
+                    },
+
+                    text() {
+                        if (error.response && error.response.data !== undefined) {
+                            const d = error.response.data;
+                            return Promise.resolve(typeof d === 'string' ? d : JSON.stringify(d));
+                        }
+                        return Promise.resolve(error.message);
+                    }
+                };
+            }
+        }
+    };
+}

package/dist/css/accessibility.css

@@ -0,0 +1,119 @@
+/* Accessibility (a11y) */
+
+/* Focus styles */
+*:focus-visible {
+  outline: 2px solid var(--bg-brand);
+  outline-offset: 2px;
+}
+
+*:focus:not(:focus-visible) {
+  outline: none;
+}
+
+/* Skip link */
+.skip-link {
+  position: absolute;
+  top: -40px;
+  left: 0;
+  padding: 8px 12px;
+  background-color: var(--bg-brand);
+  color: var(--text-onbrand);
+  font-size: 13px;
+  font-weight: 500;
+  text-decoration: none;
+  z-index: 1000;
+  transition: top 0.2s ease;
+}
+
+.skip-link:focus {
+  top: 0;
+}
+
+/* Screen reader only */
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+/* High contrast mode */
+@media (prefers-contrast: high) {
+  :root {
+    --border-neutral-l1: #000000;
+    --border-neutral-l2: #000000;
+    --border-neutral-l3: #000000;
+  }
+
+  .ds-btn {
+    border-width: 2px;
+  }
+  
+  .ds-input {
+    border-width: 2px;
+  }
+  
+  .ds-card {
+    border-width: 2px;
+  }
+}
+
+/* Reduced motion */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+
+/* Keyboard navigation */
+.ds-btn:not(:disabled):focus-visible,
+.ds-input:focus-visible,
+.ds-toggle input:focus-visible + .ds-toggle__track {
+  outline: 2px solid var(--bg-brand);
+  outline-offset: 2px;
+}
+
+/* Active states for keyboard users */
+.ds-btn:not(:disabled):active,
+.ds-btn:not(:disabled):focus:active {
+  transform: translateY(1px);
+}
+
+/* Visible focus for better keyboard navigation */
+.ds-dashboard__sidebar-item:focus-visible,
+.ds-activityrail__item:focus-visible,
+.ds-statusbar__item:focus-visible {
+  outline: 2px solid var(--bg-brand);
+  outline-offset: 2px;
+}
+
+/* Color contrast */
+.ds-statcard__delta.is-up {
+  color: var(--status-success-default);
+}
+
+.ds-statcard__delta.is-down {
+  color: var(--status-error-default);
+}
+
+/* Selection color */
+::selection {
+  background-color: var(--bg-brand-popup);
+  color: var(--text-brand);
+}
+
+/* Clearfix */
+.ds-clearfix::after {
+  content: '';
+  display: table;
+  clear: both;
+}