@svadmin/core 0.0.2 → 0.0.6

package/src/inferencer.ts

@@ -0,0 +1,247 @@
+/**
+ * @svadmin/inferencer
+ *
+ * Analyzes API response data and infers ResourceDefinition + FieldDefinition[].
+ * Can also generate copy-paste-ready Svelte component code.
+ */
+import type { FieldDefinition, ResourceDefinition } from '@svadmin/core';
+
+// ─── Field Type Inference ────────────────────────────────────
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const URL_RE = /^https?:\/\//;
+const IMAGE_RE = /\.(png|jpe?g|gif|svg|webp|avif|ico)(\?.*)?$/i;
+const PHONE_RE = /^\+?[\d\s\-()]{7,}$/;
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2})/;
+const COLOR_RE = /^#([0-9a-fA-F]{3,8})$/;
+
+type InferredType = FieldDefinition['type'];
+
+/**
+ * Infer the svadmin field type from a single sample value.
+ */
+export function inferFieldType(key: string, value: unknown): InferredType {
+  if (value === null || value === undefined) return 'text';
+
+  if (typeof value === 'boolean') return 'boolean';
+  if (typeof value === 'number') return 'number';
+
+  if (Array.isArray(value)) {
+    if (value.length > 0 && typeof value[0] === 'string') {
+      if (value.every(v => typeof v === 'string' && IMAGE_RE.test(v))) return 'images';
+      return 'tags';
+    }
+    return 'tags';
+  }
+
+  if (typeof value === 'object') return 'json';
+
+  if (typeof value === 'string') {
+    if (COLOR_RE.test(value)) return 'color';
+    if (EMAIL_RE.test(value)) return 'email';
+    if (IMAGE_RE.test(value)) return 'image';
+    if (URL_RE.test(value)) return 'url';
+    if (PHONE_RE.test(value)) return 'phone';
+    if (ISO_DATE_RE.test(value)) return 'date';
+    if (value.length > 200) return 'textarea';
+
+    // Heuristic: key name hints
+    const lk = key.toLowerCase();
+    if (lk.includes('email')) return 'email';
+    if (lk.includes('phone') || lk.includes('tel') || lk.includes('mobile')) return 'phone';
+    if (lk.includes('url') || lk.includes('link') || lk.includes('website')) return 'url';
+    if (lk.includes('avatar') || lk.includes('image') || lk.includes('photo') || lk.includes('thumbnail') || lk.includes('logo')) return 'image';
+    if (lk.includes('color') || lk.includes('colour')) return 'color';
+    if (lk.includes('description') || lk.includes('content') || lk.includes('body') || lk.includes('bio') || lk.includes('summary')) return 'textarea';
+    if (lk === 'created_at' || lk === 'updated_at' || lk.endsWith('_at') || lk.endsWith('_date') || lk.includes('date')) return 'date';
+
+    return 'text';
+  }
+
+  return 'text';
+}
+
+// ─── Relation Detection ──────────────────────────────────────
+
+const RELATION_SUFFIXES = ['_id', 'Id', '_ID'];
+
+function isLikelyRelation(key: string): string | null {
+  for (const suffix of RELATION_SUFFIXES) {
+    if (key.endsWith(suffix)) {
+      const resource = key.slice(0, -suffix.length);
+      // Pluralize naively
+      return resource.endsWith('s') ? resource : resource + 's';
+    }
+  }
+  return null;
+}
+
+// ─── Core: Infer from Sample Data ────────────────────────────
+
+export interface InferResult {
+  fields: FieldDefinition[];
+  resource: ResourceDefinition;
+  code: string;
+}
+
+/**
+ * Analyze a sample data array and produce a ResourceDefinition.
+ * @param resourceName - Name of the resource (e.g. "posts")
+ * @param sampleData  - An array of records from the API
+ * @param options      - Additional configuration
+ */
+export function inferResource(
+  resourceName: string,
+  sampleData: Record<string, unknown>[],
+  options: {
+    primaryKey?: string;
+    label?: string;
+  } = {}
+): InferResult {
+  const primaryKey = options.primaryKey ?? 'id';
+  const label = options.label ?? capitalize(resourceName);
+
+  if (!sampleData.length) {
+    return {
+      fields: [],
+      resource: { name: resourceName, label, fields: [], primaryKey },
+      code: `// No data available to infer fields for "${resourceName}".`,
+    };
+  }
+
+  // Gather all unique keys across all records
+  const keySet = new Set<string>();
+  for (const row of sampleData) {
+    for (const k of Object.keys(row)) keySet.add(k);
+  }
+
+  // For each key, infer from all non-null values
+  const fields: FieldDefinition[] = [];
+  for (const key of keySet) {
+    // Collect non-null values
+    const values = sampleData
+      .map(r => r[key])
+      .filter(v => v !== null && v !== undefined);
+
+    const sampleValue = values[0];
+    let inferredType = inferFieldType(key, sampleValue);
+
+    // Cross-validate: if most values for this key are of a different type, use majority
+    const typeCounts = new Map<InferredType, number>();
+    for (const v of values) {
+      const t = inferFieldType(key, v);
+      typeCounts.set(t, (typeCounts.get(t) ?? 0) + 1);
+    }
+    let maxCount = 0;
+    for (const [t, count] of typeCounts) {
+      if (count > maxCount) {
+        maxCount = count;
+        inferredType = t;
+      }
+    }
+
+    // Check for relation
+    const relatedResource = isLikelyRelation(key);
+
+    // Check if it looks like a select (few unique string values)
+    const uniqueStrings = new Set(values.filter(v => typeof v === 'string') as string[]);
+    const isSelect = inferredType === 'text' && uniqueStrings.size > 1 && uniqueStrings.size <= 10 && values.length >= 5;
+
+    const field: FieldDefinition = {
+      key,
+      label: humanize(key),
+      type: relatedResource ? 'relation' : isSelect ? 'select' : inferredType,
+      sortable: inferredType === 'text' || inferredType === 'number' || inferredType === 'date',
+      searchable: inferredType === 'text' || inferredType === 'email',
+      showInList: key !== primaryKey && inferredType !== 'textarea' && inferredType !== 'json' && inferredType !== 'richtext',
+      showInForm: key !== primaryKey,
+    };
+
+    if (relatedResource) {
+      field.resource = relatedResource;
+      field.optionLabel = 'name';
+      field.optionValue = 'id';
+    }
+
+    if (isSelect) {
+      field.options = [...uniqueStrings].map(v => ({ label: capitalize(v), value: v }));
+    }
+
+    fields.push(field);
+  }
+
+  // Sort: primaryKey first, then alphabetically
+  fields.sort((a, b) => {
+    if (a.key === primaryKey) return -1;
+    if (b.key === primaryKey) return 1;
+    return a.key.localeCompare(b.key);
+  });
+
+  const resource: ResourceDefinition = {
+    name: resourceName,
+    label,
+    primaryKey,
+    fields,
+    canCreate: true,
+    canEdit: true,
+    canDelete: true,
+    canShow: true,
+  };
+
+  const code = generateCode(resource);
+
+  return { fields, resource, code };
+}
+
+// ─── Code Generation ─────────────────────────────────────────
+
+function generateCode(resource: ResourceDefinition): string {
+  const fieldsCode = resource.fields.map(f => {
+    const lines = [
+      `    { key: '${f.key}', label: '${f.label}', type: '${f.type}'`,
+    ];
+    if (f.sortable) lines.push(`      sortable: true`);
+    if (f.searchable) lines.push(`      searchable: true`);
+    if (f.showInList === false) lines.push(`      showInList: false`);
+    if (f.showInForm === false) lines.push(`      showInForm: false`);
+    if (f.resource) {
+      lines.push(`      resource: '${f.resource}'`);
+      lines.push(`      optionLabel: '${f.optionLabel}'`);
+      lines.push(`      optionValue: '${f.optionValue}'`);
+    }
+    if (f.options) {
+      lines.push(`      options: ${JSON.stringify(f.options)}`);
+    }
+
+    return lines.join(',\n') + ' }';
+  }).join(',\n');
+
+  return `import type { ResourceDefinition } from '@svadmin/core';
+
+export const ${resource.name}Resource: ResourceDefinition = {
+  name: '${resource.name}',
+  label: '${resource.label}',
+  primaryKey: '${resource.primaryKey ?? 'id'}',
+  canCreate: true,
+  canEdit: true,
+  canDelete: true,
+  canShow: true,
+  fields: [
+${fieldsCode}
+  ],
+};
+`;
+}
+
+// ─── Utilities ───────────────────────────────────────────────
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+function humanize(key: string): string {
+  return key
+    .replace(/_/g, ' ')
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .replace(/\b\w/g, c => c.toUpperCase());
+}

package/src/notification.svelte.ts

@@ -0,0 +1,45 @@
+// Notification Provider — pluggable notification system
+// Falls back to built-in toast when no provider is set
+
+import { toast } from './toast.svelte';
+import type { NotificationProvider } from './types';
+
+let notificationProvider: NotificationProvider | null = null;
+
+export function setNotificationProvider(provider: NotificationProvider): void {
+  notificationProvider = provider;
+}
+
+export function getNotificationProvider(): NotificationProvider | null {
+  return notificationProvider;
+}
+
+/**
+ * Send a notification through the configured provider, or fall back to toast.
+ */
+export function notify(params: {
+  type: 'success' | 'error' | 'warning' | 'info';
+  message: string;
+  description?: string;
+  key?: string;
+}): void {
+  if (notificationProvider) {
+    notificationProvider.open(params);
+  } else {
+    // Fallback to built-in toast
+    const { type, message } = params;
+    switch (type) {
+      case 'success': toast.success(message); break;
+      case 'error': toast.error(message); break;
+      case 'warning': toast.warning(message); break;
+      case 'info': toast.info(message); break;
+    }
+  }
+}
+
+/**
+ * Close a notification by key (only works with custom provider).
+ */
+export function closeNotification(key: string): void {
+  notificationProvider?.close(key);
+}

package/src/permissions.test.ts

@@ -0,0 +1,55 @@
+// Unit tests for permissions module
+import { describe, test, expect, beforeEach } from 'bun:test';
+import { setAccessControl, canAccess, canAccessAsync } from './permissions';
+import type { Action } from './permissions';
+
+describe('permissions', () => {
+  beforeEach(() => {
+    // Reset to no access control (allow all)
+    setAccessControl((() => ({ can: true })) as Parameters<typeof setAccessControl>[0]);
+  });
+
+  test('canAccess returns { can: true } when no deny rules', () => {
+    const result = canAccess('posts', 'list' as Action);
+    expect(result.can).toBe(true);
+  });
+
+  test('canAccess respects deny rule', () => {
+    setAccessControl((_resource: string, action: Action) => {
+      if (action === 'delete') return { can: false, reason: 'Denied' };
+      return { can: true };
+    });
+    expect(canAccess('posts', 'delete')).toEqual({ can: false, reason: 'Denied' });
+    expect(canAccess('posts', 'list')).toEqual({ can: true });
+  });
+
+  test('canAccess returns { can: true } when async fn used sync', () => {
+    setAccessControl(async () => ({ can: false }));
+    // Should warn and default to { can: true }
+    const result = canAccess('posts', 'list');
+    expect(result.can).toBe(true);
+  });
+
+  test('canAccessAsync resolves with allowed status', async () => {
+    setAccessControl(async () => ({ can: true }));
+    const result = await canAccessAsync('posts', 'edit');
+    expect(result.can).toBe(true);
+  });
+
+  test('canAccessAsync resolves with denied status', async () => {
+    setAccessControl(async (_r: string, _a: Action) => ({ can: false, reason: 'No permission' }));
+    const result = await canAccessAsync('users', 'delete');
+    expect(result.can).toBe(false);
+    expect(result.reason).toBe('No permission');
+  });
+
+  test('resource-specific rules', () => {
+    setAccessControl((resource: string, action: Action) => {
+      if (resource === 'users' && action === 'delete') return { can: false, reason: 'Cannot delete users' };
+      return { can: true };
+    });
+    expect(canAccess('users', 'delete').can).toBe(false);
+    expect(canAccess('users', 'list').can).toBe(true);
+    expect(canAccess('posts', 'delete').can).toBe(true);
+  });
+});

package/src/router-provider.test.ts

@@ -0,0 +1,71 @@
+// Unit tests for RouterProvider implementations
+// Router provider tests need a DOM environment.
+// Skip if window is not available (CI without happy-dom).
+import { describe, test, expect } from 'bun:test';
+import { createHashRouterProvider, createHistoryRouterProvider } from './router-provider';
+
+const hasWindow = typeof globalThis.window !== 'undefined';
+
+describe('createHashRouterProvider (unit — no DOM)', () => {
+  test('returns provider with go, back, parse methods', () => {
+    const provider = createHashRouterProvider();
+    expect(typeof provider.go).toBe('function');
+    expect(typeof provider.back).toBe('function');
+    expect(typeof provider.parse).toBe('function');
+  });
+});
+
+describe('createHistoryRouterProvider (unit — no DOM)', () => {
+  test('returns provider with go, back, parse methods', () => {
+    const provider = createHistoryRouterProvider();
+    expect(typeof provider.go).toBe('function');
+    expect(typeof provider.back).toBe('function');
+    expect(typeof provider.parse).toBe('function');
+  });
+
+  test('accepts basePath argument', () => {
+    const provider = createHistoryRouterProvider('/admin');
+    expect(typeof provider.parse).toBe('function');
+  });
+});
+
+// DOM-dependent tests — only run if window is available
+describe.skipIf(!hasWindow)('createHashRouterProvider (DOM)', () => {
+  test('parse returns empty segments for root', () => {
+    window.location.hash = '';
+    const provider = createHashRouterProvider();
+    const parsed = provider.parse();
+    expect(parsed.pathname).toBe('/');
+  });
+
+  test('parse extracts resource from hash', () => {
+    window.location.hash = '#/posts';
+    const provider = createHashRouterProvider();
+    const parsed = provider.parse();
+    expect(parsed.pathname).toBe('/posts');
+    expect(parsed.resource).toBe('posts');
+  });
+
+  test('parse extracts resource, action, and id', () => {
+    window.location.hash = '#/posts/edit/42';
+    const provider = createHashRouterProvider();
+    const parsed = provider.parse();
+    expect(parsed.resource).toBe('posts');
+    expect(parsed.action).toBe('edit');
+    expect(parsed.id).toBe('42');
+  });
+
+  test('parse extracts query params from hash', () => {
+    window.location.hash = '#/posts?page=2&sort=name';
+    const provider = createHashRouterProvider();
+    const parsed = provider.parse();
+    expect(parsed.params.page).toBe('2');
+    expect(parsed.params.sort).toBe('name');
+  });
+
+  test('go sets window.location.hash', () => {
+    const provider = createHashRouterProvider();
+    provider.go({ to: '/users' });
+    expect(window.location.hash).toBe('#/users');
+  });
+});

package/src/router-provider.ts

@@ -0,0 +1,100 @@
+// Router Provider — abstracts routing strategy (hash, history, SvelteKit, etc.)
+
+export interface RouterProvider {
+  /** Navigate to a path */
+  go: (options: {
+    to: string;
+    query?: Record<string, string>;
+    hash?: string;
+    type?: 'push' | 'replace';
+  }) => void;
+  /** Navigate back */
+  back: () => void;
+  /** Parse current URL into structured route info */
+  parse: () => {
+    resource?: string;
+    action?: string;
+    id?: string;
+    params: Record<string, string>;
+    pathname: string;
+  };
+}
+
+// ─── Hash Router (default) ──────────────────────────────────
+
+export function createHashRouterProvider(): RouterProvider {
+  return {
+    go({ to, query, type = 'push' }) {
+      let url = `#${to}`;
+      if (query) {
+        const params = new URLSearchParams(query).toString();
+        if (params) url += `?${params}`;
+      }
+      if (type === 'replace') {
+        window.location.replace(url);
+      } else {
+        window.location.hash = to;
+      }
+    },
+    back() {
+      history.back();
+    },
+    parse() {
+      const hash = window.location.hash.slice(1) || '/';
+      const [pathname, queryString] = hash.split('?');
+      const params: Record<string, string> = {};
+      if (queryString) {
+        for (const [k, v] of new URLSearchParams(queryString).entries()) {
+          params[k] = v;
+        }
+      }
+      const segments = pathname.split('/').filter(Boolean);
+      return {
+        resource: segments[0],
+        action: segments[1],
+        id: segments[2],
+        params,
+        pathname,
+      };
+    },
+  };
+}
+
+// ─── History Router (HTML5 pushState) ───────────────────────
+
+export function createHistoryRouterProvider(basePath = ''): RouterProvider {
+  return {
+    go({ to, query, type = 'push' }) {
+      let url = `${basePath}${to}`;
+      if (query) {
+        const params = new URLSearchParams(query).toString();
+        if (params) url += `?${params}`;
+      }
+      if (type === 'replace') {
+        history.replaceState(null, '', url);
+      } else {
+        history.pushState(null, '', url);
+      }
+      // Dispatch event so other parts of the app can react
+      window.dispatchEvent(new PopStateEvent('popstate'));
+    },
+    back() {
+      history.back();
+    },
+    parse() {
+      const pathname = window.location.pathname.replace(basePath, '') || '/';
+      const params: Record<string, string> = {};
+      for (const [k, v] of new URLSearchParams(window.location.search).entries()) {
+        params[k] = v;
+      }
+      const segments = pathname.split('/').filter(Boolean);
+      return {
+        resource: segments[0],
+        action: segments[1],
+        id: segments[2],
+        params,
+        pathname,
+      };
+    },
+  };
+}

package/src/types.ts

@@ -233,4 +233,6 @@ export interface FieldDefinition {
   resource?: string;       // related resource name
   optionLabel?: string;    // field to use as label
   optionValue?: string;    // field to use as value
+  // Validation
+  validate?: (value: unknown) => string | null;
 }

package/src/useCan.ts

@@ -0,0 +1,37 @@
+// useCan — reactive permission check hook
+
+import { canAccessAsync } from './permissions';
+import type { Action, AccessControlResult } from './permissions';
+
+interface UseCanResult {
+  allowed: boolean;
+  reason?: string;
+  isLoading: boolean;
+}
+
+/**
+ * Reactive permission check. Calls canAccessAsync() and returns reactive state.
+ * Usage: const can = useCan('posts', 'delete');
+ *        if (can.allowed) { ... }
+ */
+export function useCan(resource: string, action: Action, params?: Record<string, unknown>): UseCanResult {
+  let allowed = $state(true);
+  let reason = $state<string | undefined>(undefined);
+  let isLoading = $state(true);
+
+  // Run the async check
+  canAccessAsync(resource, action, params).then((result: AccessControlResult) => {
+    allowed = result.can;
+    reason = result.reason;
+    isLoading = false;
+  }).catch(() => {
+    allowed = true; // default to allowed on error
+    isLoading = false;
+  });
+
+  return {
+    get allowed() { return allowed; },
+    get reason() { return reason; },
+    get isLoading() { return isLoading; },
+  };
+}

package/src/useParsed.ts

@@ -0,0 +1,74 @@
+// useParsed — parse current URL hash into structured route info
+
+import { currentPath } from './router';
+import { getResources } from './context';
+
+interface ParsedRoute {
+  resource?: string;
+  action?: 'list' | 'create' | 'edit' | 'show';
+  id?: string;
+  params: Record<string, string>;
+}
+
+/**
+ * Parse the current hash URL into a structured route object.
+ * Returns reactive properties that update when the URL changes.
+ *
+ * Usage:
+ *   const parsed = useParsed();
+ *   // parsed.resource === 'posts'
+ *   // parsed.action === 'edit'
+ *   // parsed.id === '123'
+ */
+export function useParsed(): ParsedRoute {
+  const path = $derived(currentPath());
+  const resources = $derived((() => { try { return getResources(); } catch { return []; } })());
+
+  const parsed = $derived.by(() => {
+    const p = path;
+    const result: ParsedRoute = { params: {} };
+
+    // Parse query params from hash
+    const [pathname, queryString] = p.split('?');
+    if (queryString) {
+      const sp = new URLSearchParams(queryString);
+      for (const [k, v] of sp.entries()) {
+        result.params[k] = v;
+      }
+    }
+
+    const segments = pathname.split('/').filter(Boolean);
+    if (segments.length === 0) return result;
+
+    // First segment is typically the resource name
+    const resourceNames = resources.map(r => r.name);
+    if (resourceNames.includes(segments[0])) {
+      result.resource = segments[0];
+
+      if (segments.length === 1) {
+        result.action = 'list';
+      } else if (segments[1] === 'create') {
+        result.action = 'create';
+      } else if (segments[1] === 'edit' && segments[2]) {
+        result.action = 'edit';
+        result.id = segments[2];
+      } else if (segments[1] === 'show' && segments[2]) {
+        result.action = 'show';
+        result.id = segments[2];
+      } else if (segments[1]) {
+        // Legacy: /:resource/:id
+        result.action = 'show';
+        result.id = segments[1];
+      }
+    }
+
+    return result;
+  });
+
+  return {
+    get resource() { return parsed.resource; },
+    get action() { return parsed.action; },
+    get id() { return parsed.id; },
+    get params() { return parsed.params; },
+  };
+}