@kupola/kupola 1.2.0 → 1.4.0

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/css/components-ext.css

@@ -1403,6 +1403,42 @@
   border-radius: 50%;
 }
 
+/* IMP-009: Skeleton size variants */
+.ds-skeleton--text {
+  height: 14px;
+  margin-bottom: var(--spacer-8);
+}
+
+.ds-skeleton--heading {
+  height: 24px;
+  width: 40%;
+  margin-bottom: var(--spacer-12);
+}
+
+.ds-skeleton--block {
+  height: 200px;
+}
+
+.ds-skeleton--avatar {
+  width: 40px;
+  height: 40px;
+}
+
+.ds-skeleton--button {
+  height: 28px;
+  width: 80px;
+}
+
+.ds-skeleton--input {
+  height: 28px;
+  width: 100%;
+}
+
+.ds-skeleton--table {
+  height: 200px;
+  width: 100%;
+}
+
 @keyframes ds-skeleton-pulse {
   0%, 100% { opacity: 1; }
   50% { opacity: 0.5; }
@@ -2661,6 +2697,17 @@
   right: 2px;
 }
 
+/* IMP-006: Badge info variant */
+.ds-badge--info {
+  background: var(--status-info-surface-l1);
+  color: var(--status-info-default);
+}
+
+.ds-badge--neutral {
+  background: var(--bg-overlay-l2);
+  color: var(--text-tertiary);
+}
+
 /* ── Tooltip ──────────────────────────────────────────────── */
 [data-tooltip] {
   position: relative;
@@ -4162,4 +4209,114 @@
 
 .ds-virtual-list--horizontal .ds-virtual-list__item:last-child {
   border-right: none;
+}
+
+/* ── Tree (IMP-008) ──────────────────────────────────────── */
+.ds-tree {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  font-size: var(--body-sm-font-size, 13px);
+}
+
+.ds-tree ul {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+
+.ds-tree__item {
+  display: flex;
+  align-items: center;
+  gap: var(--spacer-6);
+  padding: var(--spacer-4) var(--spacer-8);
+  border-radius: var(--radius-4);
+  cursor: default;
+  transition: background-color 0.12s ease;
+  user-select: none;
+}
+
+.ds-tree__item:hover {
+  background-color: var(--bg-overlay-l1);
+}
+
+.ds-tree__item.is-selected {
+  background-color: var(--bg-brand-popup);
+}
+
+.ds-tree__toggle {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+  height: 16px;
+  flex-shrink: 0;
+  cursor: pointer;
+  color: var(--icon-secondary);
+  transition: transform 0.15s ease;
+  background: none;
+  border: none;
+  padding: 0;
+}
+
+.ds-tree__toggle::before {
+  content: '';
+  display: block;
+  width: 0;
+  height: 0;
+  border-left: 5px solid currentColor;
+  border-top: 3.5px solid transparent;
+  border-bottom: 3.5px solid transparent;
+}
+
+.ds-tree__toggle.is-open {
+  transform: rotate(90deg);
+}
+
+.ds-tree__toggle.is-leaf {
+  visibility: hidden;
+}
+
+.ds-tree__checkbox {
+  width: 14px;
+  height: 14px;
+  flex-shrink: 0;
+  accent-color: var(--bg-brand);
+  cursor: pointer;
+}
+
+.ds-tree__icon {
+  width: 16px;
+  height: 16px;
+  flex-shrink: 0;
+  color: var(--icon-secondary);
+}
+
+.ds-tree__label {
+  flex: 1;
+  color: var(--text-default);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.ds-tree__badge {
+  font-size: var(--body-xs-font-size, 10px);
+  color: var(--text-tertiary);
+  margin-left: auto;
+}
+
+.ds-tree__children {
+  padding-left: var(--spacer-20);
+  border-left: 1px solid var(--border-neutral-l1);
+  margin-left: 7px;
+}
+
+/* Tree line guides */
+.ds-tree--lined .ds-tree__children {
+  border-left-color: var(--border-neutral-l1);
+}
+
+.ds-tree--compact .ds-tree__item {
+  padding: var(--spacer-2) var(--spacer-8);
 }

package/css/components.css

@@ -540,6 +540,24 @@
     .ds-input.is-error { border-color: var(--bg-error-default); }
     .ds-input.is-success { border-color: var(--bg-success-default); }
     
+        /* BUG-003 fix: ensure <select class="ds-input"> matches <input> height/padding */
+        select.ds-input,
+        .ds-input select {
+          height: 28px;
+          padding: 0 var(--spacer-24) 0 var(--spacer-12);
+          appearance: none;
+          -webkit-appearance: none;
+          -moz-appearance: none;
+          background-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 24 24' fill='none' stroke='%239599A6' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'><polyline points='6 9 12 15 18 9'></polyline></svg>");
+          background-repeat: no-repeat;
+          background-position: right 8px center;
+          background-size: 12px;
+          cursor: pointer;
+          font: inherit;
+          color: var(--text-default);
+        }
+        select.ds-input::-ms-expand { display: none; }
+    
     .ds-input__status-icon {
       position: absolute;
       right: 12px;
@@ -980,6 +998,18 @@
     }
     .ds-table__pagination { display: flex; align-items: center; gap: var(--spacer-8); }
 
+    /* Table variants (IMP-001) */
+    .ds-table--striped tbody tr:nth-child(even) { background: var(--bg-base-secondary); }
+    .ds-table--hover tbody tr:hover { background: var(--bg-overlay-l1); cursor: default; }
+    .ds-table--compact th,
+    .ds-table--compact td { padding: var(--spacer-6) var(--spacer-8); font-size: var(--body-xs-font-size); }
+
+    /* Table cell utilities */
+    .ds-td--strong { font-weight: 500; color: var(--text-default); }
+    .ds-td--actions { display: flex; gap: var(--spacer-4); align-items: center; }
+    .ds-td--mono { font-family: var(--code-editor-font-family); font-variant-numeric: tabular-nums; }
+    .ds-td--truncate { max-width: 200px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+
 /* ── Tabs ──────────────────────────────────────────────────── */
 /* ===== Tabs ===== */
     .ds-tabs { display: flex; gap: var(--spacer-24); border-bottom: 1px solid var(--border-neutral-l1); }
@@ -1311,6 +1341,45 @@
   margin-top: var(--spacer-16);
 }
 
+/* IMP-004: Flat aliases — use these without BEM __ nesting */
+.ds-form-group {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacer-6);
+  margin-bottom: var(--spacer-12);
+}
+
+.ds-form-label {
+  display: block;
+  font-size: var(--body-sm-font-size);
+  font-weight: var(--font-weight-medium);
+  color: var(--text-default);
+  margin-bottom: var(--spacer-4);
+}
+
+.ds-form-row {
+  display: grid;
+  grid-template-columns: repeat(2, 1fr);
+  gap: var(--spacer-12);
+}
+
+.ds-form-row--3 {
+  grid-template-columns: repeat(3, 1fr);
+}
+
+.ds-form-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: var(--spacer-8);
+  margin-top: var(--spacer-16);
+}
+
+.ds-form-hint {
+  font-size: var(--body-xs-font-size);
+  color: var(--text-tertiary);
+  margin-top: var(--spacer-2);
+}
+
 .ds-radio-group {
   display: flex;
   gap: var(--spacer-16);