@djangocfg/ext-base 1.0.3 → 1.0.4

package/dist/hooks.cjs

@@ -0,0 +1,437 @@
+'use strict';
+
+var consola = require('consola');
+var React = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+var swr = require('swr');
+var auth = require('@djangocfg/api/auth');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var React__default = /*#__PURE__*/_interopDefault(React);
+
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/types/context.ts
+var EXTENSION_CATEGORIES = [
+  { title: "Forms", value: "forms" },
+  { title: "Payments", value: "payments" },
+  { title: "Content", value: "content" },
+  { title: "Support", value: "support" },
+  { title: "Utilities", value: "utilities" },
+  { title: "Analytics", value: "analytics" },
+  { title: "Security", value: "security" },
+  { title: "Integration", value: "integration" },
+  { title: "Other", value: "other" }
+];
+
+// src/utils/createExtensionConfig.ts
+function replaceWorkspaceDeps(deps) {
+  if (!deps) return void 0;
+  const result = {};
+  for (const [key, value] of Object.entries(deps)) {
+    result[key] = value === "workspace:*" ? "latest" : value;
+  }
+  return result;
+}
+function createExtensionConfig(packageJson, config) {
+  const author = typeof packageJson.author === "string" ? packageJson.author : packageJson.author?.name || "Unknown";
+  const githubUrl = typeof packageJson.repository === "string" ? packageJson.repository : packageJson.repository?.url;
+  const packageNameWithoutScope = packageJson.name.split("/").pop() || packageJson.name;
+  const downloadUrl = `https://registry.npmjs.org/${packageJson.name}/-/${packageNameWithoutScope}-${packageJson.version}.tgz`;
+  const marketplaceId = packageJson.name.replace("@", "").replace("/", "-");
+  return {
+    // From package.json
+    name: config.name,
+    version: packageJson.version,
+    author,
+    description: packageJson.description,
+    keywords: packageJson.keywords,
+    license: packageJson.license,
+    homepage: packageJson.homepage,
+    githubUrl,
+    packageDependencies: replaceWorkspaceDeps(packageJson.dependencies),
+    packagePeerDependencies: replaceWorkspaceDeps(packageJson.peerDependencies),
+    packageDevDependencies: replaceWorkspaceDeps(packageJson.devDependencies),
+    // From manual config
+    displayName: config.displayName,
+    category: config.category,
+    features: config.features,
+    examples: config.examples,
+    minVersion: config.minVersion,
+    githubStars: config.githubStars,
+    // Auto-generated
+    npmUrl: `https://www.npmjs.com/package/${packageJson.name}`,
+    marketplaceId,
+    // Only generate marketplace URL for official @djangocfg extensions
+    marketplaceUrl: packageJson.name.startsWith("@djangocfg/ext-") ? `https://hub.djangocfg.com/extensions/${marketplaceId}` : void 0,
+    installCommand: `pnpm add ${packageJson.name}`,
+    downloadUrl,
+    tags: packageJson.keywords,
+    preview: `https://unpkg.com/${packageJson.name}@latest/preview.png`
+  };
+}
+
+// package.json
+var package_default = {
+  name: "@djangocfg/ext-base",
+  version: "1.0.4",
+  description: "Base utilities and common code for DjangoCFG extensions",
+  keywords: [
+    "django",
+    "djangocfg",
+    "extension",
+    "base",
+    "utilities",
+    "typescript",
+    "react"
+  ],
+  author: {
+    name: "DjangoCFG",
+    url: "https://djangocfg.com"
+  },
+  homepage: "https://hub.djangocfg.com/extensions/djangocfg-ext-base",
+  repository: {
+    type: "git",
+    url: "https://github.com/markolofsen/django-cfg.git",
+    directory: "extensions/base"
+  },
+  license: "MIT",
+  peerDependencies: {
+    "@djangocfg/api": "workspace:*",
+    consola: "^3.4.2",
+    react: "^18 || ^19",
+    "react-dom": "^18 || ^19",
+    swr: "^2.3.7"
+  },
+  dependencies: {
+    chalk: "^5.3.0",
+    consola: "^3.4.2",
+    picocolors: "^1.1.1",
+    prompts: "^2.4.2"
+  },
+  devDependencies: {
+    "@djangocfg/api": "workspace:*",
+    "@djangocfg/typescript-config": "workspace:*",
+    "@types/node": "^24.7.2",
+    "@types/prompts": "^2.4.9",
+    "@types/react": "^19.0.0",
+    swr: "^2.3.7",
+    tsup: "^8.5.0",
+    tsx: "^4.19.2",
+    typescript: "^5.9.3"
+  }
+};
+
+// src/extensionConfig.ts
+var extensionConfig = createExtensionConfig(package_default, {
+  name: "base",
+  displayName: "Extension Base",
+  category: "utilities",
+  features: [
+    "CLI for creating extensions",
+    "Next.js 15 playground for rapid development",
+    "Smart Provider Pattern for flexible component usage",
+    "Extension context and provider system",
+    "Pagination hooks (standard & infinite scroll)",
+    "API client utilities with auth integration",
+    "Type-safe context creation helpers",
+    "Logging system with structured output",
+    "Environment detection (dev, prod, static)",
+    "TypeScript types and utilities"
+  ],
+  minVersion: "2.0.0",
+  examples: [
+    {
+      title: "Create Extension with CLI",
+      description: "Interactive wizard with playground environment",
+      code: `# Create extension with interactive wizard
+pnpm dlx @djangocfg/ext-base create
+
+# Quick test extension (auto-cleanup)
+pnpm dlx @djangocfg/ext-base test
+
+# List all extensions
+pnpm dlx @djangocfg/ext-base list`,
+      language: "bash"
+    },
+    {
+      title: "Development with Playground",
+      description: "Start Next.js playground for rapid testing",
+      code: `cd your-extension
+
+# Start playground (auto-builds extension + opens browser)
+pnpm dev:playground
+
+# Build for production
+pnpm build
+
+# Type check
+pnpm check`,
+      language: "bash"
+    },
+    {
+      title: "Smart Provider Pattern",
+      description: "Components that work standalone or with shared context",
+      code: `import { withSmartProvider } from '@your-org/my-extension';
+
+// Your component
+function MyComponent() {
+  const { data } = useMyExtension();
+  return <div>{data}</div>;
+}
+
+// Wrap with smart provider
+export const MySmartComponent = withSmartProvider(MyComponent);
+
+// Usage 1: Standalone (auto-wrapped)
+<MySmartComponent />
+
+// Usage 2: Manual provider (shared context)
+<MyExtensionProvider>
+  <MySmartComponent />
+  <MySmartComponent />
+</MyExtensionProvider>`,
+      language: "tsx"
+    },
+    {
+      title: "Extension Provider",
+      description: "Register and wrap your extension",
+      code: `import { ExtensionProvider } from '@djangocfg/ext-base/hooks';
+import { extensionConfig } from './config';
+
+export function MyExtensionProvider({ children }) {
+  return (
+    <ExtensionProvider metadata={extensionConfig}>
+      {children}
+    </ExtensionProvider>
+  );
+}`,
+      language: "tsx"
+    },
+    {
+      title: "Pagination Hooks",
+      description: "Built-in hooks for standard and infinite scroll",
+      code: `import { usePagination, useInfinitePagination } from '@djangocfg/ext-base/hooks';
+
+// Standard pagination
+const { items, page, totalPages, nextPage, prevPage } = usePagination({
+  keyPrefix: 'articles',
+  fetcher: async (page, pageSize) => api.articles.list({ page, page_size: pageSize }),
+  pageSize: 20,
+});
+
+// Infinite scroll
+const { items, isLoading, hasMore, loadMore } = useInfinitePagination({
+  keyPrefix: 'articles',
+  fetcher: async (page, pageSize) => api.articles.list({ page, page_size: pageSize }),
+  pageSize: 20,
+});`,
+      language: "tsx"
+    }
+  ]
+});
+
+// src/metadata.ts
+({
+  version: package_default.version,
+  npmUrl: `https://www.npmjs.com/package/${package_default.name}`,
+  installCommand: `pnpm add ${package_default.name}`,
+  packagePeerDependencies: package_default.peerDependencies});
+
+// src/config.ts
+var isDevelopment = process.env.NODE_ENV === "development";
+var isProduction = process.env.NODE_ENV === "production";
+var isStaticBuild = process.env.STATIC_BUILD === "true";
+function getApiUrl() {
+  return process.env.NEXT_PUBLIC_API_URL || "/api";
+}
+
+// src/api/createExtensionAPI.ts
+function createExtensionAPI(APIClass) {
+  let storage;
+  try {
+    const { api: accountsApi } = __require("@djangocfg/api");
+    storage = accountsApi._storage;
+  } catch (error) {
+    storage = void 0;
+  }
+  const apiUrl = isStaticBuild ? "" : getApiUrl();
+  return new APIClass(apiUrl, storage ? { storage } : void 0);
+}
+function getSharedAuthStorage() {
+  try {
+    const { api: accountsApi } = __require("@djangocfg/api");
+    return accountsApi._storage;
+  } catch (error) {
+    return void 0;
+  }
+}
+
+// src/utils/errors.ts
+function isExtensionError(error) {
+  return typeof error === "object" && error !== null && "message" in error && "timestamp" in error;
+}
+function createExtensionError(error, code, details) {
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    message,
+    code,
+    details,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function formatErrorMessage(error) {
+  if (isExtensionError(error)) {
+    return error.code ? `[${error.code}] ${error.message}` : error.message;
+  }
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+function handleExtensionError(error, logger, callback) {
+  const extensionError = isExtensionError(error) ? error : createExtensionError(error);
+  if (logger) {
+    logger.error("Extension error:", extensionError);
+  }
+  if (callback) {
+    callback(extensionError);
+  }
+}
+var isDevelopment2 = process.env.NODE_ENV === "development";
+var LEVEL_MAP = {
+  debug: 4,
+  info: 3,
+  warn: 2,
+  error: 1
+};
+function createExtensionLogger(options) {
+  const { tag, level = "info", enabled = true } = options;
+  if (!enabled) {
+    const noop = () => {
+    };
+    return {
+      info: noop,
+      warn: noop,
+      error: noop,
+      debug: noop,
+      success: noop
+    };
+  }
+  const logLevel = isDevelopment2 ? LEVEL_MAP[level] : LEVEL_MAP.error;
+  const consola2 = consola.createConsola({
+    level: logLevel
+  }).withTag(tag);
+  return {
+    info: (...args) => consola2.info(...args),
+    warn: (...args) => consola2.warn(...args),
+    error: (...args) => consola2.error(...args),
+    debug: (...args) => consola2.debug(...args),
+    success: (...args) => consola2.success(...args)
+  };
+}
+function createExtensionContext({
+  displayName,
+  errorMessage
+}) {
+  const Context = React.createContext(void 0);
+  Context.displayName = displayName;
+  const Provider = ({ value, children }) => {
+    return /* @__PURE__ */ jsxRuntime.jsx(Context.Provider, { value, children });
+  };
+  const useContextHook = () => {
+    const context = React.useContext(Context);
+    if (context === void 0) {
+      throw new Error(
+        errorMessage || `use${displayName} must be used within ${displayName}Provider`
+      );
+    }
+    return context;
+  };
+  return {
+    Context,
+    Provider,
+    useContext: useContextHook
+  };
+}
+var DEFAULT_OPTIONS = {
+  revalidateOnFocus: false,
+  revalidateOnReconnect: false,
+  revalidateIfStale: false
+};
+var registeredExtensions = /* @__PURE__ */ new Set();
+var authWarningShown = false;
+function AuthChecker({ children }) {
+  auth.useAuth();
+  return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children });
+}
+var AuthErrorBoundary = class extends React__default.default.Component {
+  state = { hasError: false, errorMessage: "" };
+  static getDerivedStateFromError(error) {
+    if (error?.message?.includes("useAuth must be used within an AuthProvider")) {
+      return { hasError: true, errorMessage: error.message };
+    }
+    return null;
+  }
+  componentDidCatch(error) {
+    if (this.state.hasError && !authWarningShown) {
+      authWarningShown = true;
+      consola.consola.error(
+        "\u274C AuthProvider not found in parent component!\n   Extension components require AuthProvider wrapper.\n   Auto-wrapping applied as a safety measure.\n\n   Please wrap your page with <BaseApp> or <AuthProvider>:\n\n   import { BaseApp } from '@djangocfg/layouts';\n   \n   <BaseApp>\n     <YourPageWithExtensions />\n   </BaseApp>"
+      );
+    }
+  }
+  render() {
+    if (this.state.hasError) {
+      return /* @__PURE__ */ jsxRuntime.jsx(auth.AuthProvider, { children: this.props.children });
+    }
+    return this.props.children;
+  }
+};
+function ExtensionProvider({ children, metadata, options = {} }) {
+  const config = { ...DEFAULT_OPTIONS, ...options };
+  React.useEffect(() => {
+    if (registeredExtensions.has(metadata.name)) {
+      if (isDevelopment) {
+        console.warn(
+          `[ExtensionProvider] Extension "${metadata.name}" is already registered. This might indicate that the extension is mounted multiple times.`
+        );
+      }
+      return;
+    }
+    registeredExtensions.add(metadata.name);
+    if (isDevelopment) {
+      const logger = createExtensionLogger({ tag: "ext-base", level: "info" });
+      logger.info(
+        `Extension registered: ${metadata.displayName || metadata.name} v${metadata.version}`
+      );
+    }
+    return () => {
+      registeredExtensions.delete(metadata.name);
+    };
+  }, [metadata.name, metadata.version, metadata.displayName]);
+  return /* @__PURE__ */ jsxRuntime.jsx(AuthErrorBoundary, { children: /* @__PURE__ */ jsxRuntime.jsx(AuthChecker, { children: /* @__PURE__ */ jsxRuntime.jsx(swr.SWRConfig, { value: config, children }) }) });
+}
+
+exports.EXTENSION_CATEGORIES = EXTENSION_CATEGORIES;
+exports.ExtensionProvider = ExtensionProvider;
+exports.createExtensionAPI = createExtensionAPI;
+exports.createExtensionConfig = createExtensionConfig;
+exports.createExtensionContext = createExtensionContext;
+exports.createExtensionError = createExtensionError;
+exports.createExtensionLogger = createExtensionLogger;
+exports.extensionConfig = extensionConfig;
+exports.formatErrorMessage = formatErrorMessage;
+exports.getApiUrl = getApiUrl;
+exports.getSharedAuthStorage = getSharedAuthStorage;
+exports.handleExtensionError = handleExtensionError;
+exports.isDevelopment = isDevelopment;
+exports.isExtensionError = isExtensionError;
+exports.isProduction = isProduction;
+exports.isStaticBuild = isStaticBuild;

package/dist/hooks.d.cts

@@ -0,0 +1,97 @@
+import { ExtensionProviderProps } from './index.cjs';
+export { EXTENSION_CATEGORIES, ErrorHandler, ExtensionCategory, ExtensionConfigInput, ExtensionContextOptions, ExtensionError, ExtensionExample, ExtensionLogger, ExtensionMetadata, InfinitePaginationOptions, InfinitePaginationReturn, LoggerOptions, PaginatedResponse, PaginationParams, PaginationState, createExtensionConfig, createExtensionError, createExtensionLogger, extensionConfig, formatErrorMessage, getApiUrl, handleExtensionError, isDevelopment, isExtensionError, isProduction, isStaticBuild } from './index.cjs';
+export { createExtensionAPI, getSharedAuthStorage } from './api.cjs';
+import { Context, ReactNode, ReactElement } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Utility for creating typed React contexts for extensions
+ */
+
+interface CreateExtensionContextOptions<T> {
+    /** Display name for the context (for debugging) */
+    displayName: string;
+    /** Error message when hook is used outside provider */
+    errorMessage?: string;
+}
+interface ExtensionContextReturn<T> {
+    /** The React Context */
+    Context: Context<T | undefined>;
+    /** Provider component */
+    Provider: (props: {
+        value: T;
+        children: ReactNode;
+    }) => ReactElement;
+    /** Hook to access context value */
+    useContext: () => T;
+}
+/**
+ * Creates a typed React context with provider and hook
+ *
+ * @example
+ * ```tsx
+ * interface MyContextValue {
+ *   data: string[];
+ *   isLoading: boolean;
+ * }
+ *
+ * const { Provider, useContext } = createExtensionContext<MyContextValue>({
+ *   displayName: 'MyContext'
+ * });
+ *
+ * // In provider component:
+ * <Provider value={{ data: [], isLoading: false }}>
+ *   {children}
+ * </Provider>
+ *
+ * // In consumer component:
+ * const { data, isLoading } = useContext();
+ * ```
+ */
+declare function createExtensionContext<T>({ displayName, errorMessage, }: CreateExtensionContextOptions<T>): ExtensionContextReturn<T>;
+
+/**
+ * Base provider with SWR configuration for extension contexts
+ *
+ * Provides:
+ * - SWR configuration for data fetching
+ * - Extension registration and metadata management
+ * - Auth context protection (auto-wraps if missing, shows error)
+ * - Auth context from @djangocfg/api (automatically available via useAuth)
+ *
+ * @example
+ * ```tsx
+ * // In extension package:
+ * export function NewsletterProvider({ children }: { children: ReactNode }) {
+ *   return (
+ *     <ExtensionProvider
+ *       metadata={{
+ *         name: 'newsletter',
+ *         version: '1.0.0',
+ *         author: 'DjangoCFG',
+ *         displayName: 'Newsletter',
+ *         description: 'Newsletter subscription management',
+ *         icon: '📧',
+ *         license: 'MIT',
+ *         githubUrl: 'https://github.com/markolofsen/django-cfg',
+ *         keywords: ['newsletter', 'email', 'subscription'],
+ *       }}
+ *       options={{ revalidateOnFocus: true }}
+ *     >
+ *       {children}
+ *     </ExtensionProvider>
+ *   );
+ * }
+ *
+ * // In components:
+ * import { useAuth } from '@djangocfg/api/auth';
+ *
+ * function MyComponent() {
+ *   const { user, isAuthenticated } = useAuth();
+ *   // Auth is automatically available!
+ * }
+ * ```
+ */
+declare function ExtensionProvider({ children, metadata, options }: ExtensionProviderProps): react_jsx_runtime.JSX.Element;
+
+export { type CreateExtensionContextOptions, type ExtensionContextReturn, ExtensionProvider, ExtensionProviderProps, createExtensionContext };

package/dist/hooks.d.ts

@@ -0,0 +1,97 @@
+import { ExtensionProviderProps } from './index.js';
+export { EXTENSION_CATEGORIES, ErrorHandler, ExtensionCategory, ExtensionConfigInput, ExtensionContextOptions, ExtensionError, ExtensionExample, ExtensionLogger, ExtensionMetadata, InfinitePaginationOptions, InfinitePaginationReturn, LoggerOptions, PaginatedResponse, PaginationParams, PaginationState, createExtensionConfig, createExtensionError, createExtensionLogger, extensionConfig, formatErrorMessage, getApiUrl, handleExtensionError, isDevelopment, isExtensionError, isProduction, isStaticBuild } from './index.js';
+export { createExtensionAPI, getSharedAuthStorage } from './api.js';
+import { Context, ReactNode, ReactElement } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Utility for creating typed React contexts for extensions
+ */
+
+interface CreateExtensionContextOptions<T> {
+    /** Display name for the context (for debugging) */
+    displayName: string;
+    /** Error message when hook is used outside provider */
+    errorMessage?: string;
+}
+interface ExtensionContextReturn<T> {
+    /** The React Context */
+    Context: Context<T | undefined>;
+    /** Provider component */
+    Provider: (props: {
+        value: T;
+        children: ReactNode;
+    }) => ReactElement;
+    /** Hook to access context value */
+    useContext: () => T;
+}
+/**
+ * Creates a typed React context with provider and hook
+ *
+ * @example
+ * ```tsx
+ * interface MyContextValue {
+ *   data: string[];
+ *   isLoading: boolean;
+ * }
+ *
+ * const { Provider, useContext } = createExtensionContext<MyContextValue>({
+ *   displayName: 'MyContext'
+ * });
+ *
+ * // In provider component:
+ * <Provider value={{ data: [], isLoading: false }}>
+ *   {children}
+ * </Provider>
+ *
+ * // In consumer component:
+ * const { data, isLoading } = useContext();
+ * ```
+ */
+declare function createExtensionContext<T>({ displayName, errorMessage, }: CreateExtensionContextOptions<T>): ExtensionContextReturn<T>;
+
+/**
+ * Base provider with SWR configuration for extension contexts
+ *
+ * Provides:
+ * - SWR configuration for data fetching
+ * - Extension registration and metadata management
+ * - Auth context protection (auto-wraps if missing, shows error)
+ * - Auth context from @djangocfg/api (automatically available via useAuth)
+ *
+ * @example
+ * ```tsx
+ * // In extension package:
+ * export function NewsletterProvider({ children }: { children: ReactNode }) {
+ *   return (
+ *     <ExtensionProvider
+ *       metadata={{
+ *         name: 'newsletter',
+ *         version: '1.0.0',
+ *         author: 'DjangoCFG',
+ *         displayName: 'Newsletter',
+ *         description: 'Newsletter subscription management',
+ *         icon: '📧',
+ *         license: 'MIT',
+ *         githubUrl: 'https://github.com/markolofsen/django-cfg',
+ *         keywords: ['newsletter', 'email', 'subscription'],
+ *       }}
+ *       options={{ revalidateOnFocus: true }}
+ *     >
+ *       {children}
+ *     </ExtensionProvider>
+ *   );
+ * }
+ *
+ * // In components:
+ * import { useAuth } from '@djangocfg/api/auth';
+ *
+ * function MyComponent() {
+ *   const { user, isAuthenticated } = useAuth();
+ *   // Auth is automatically available!
+ * }
+ * ```
+ */
+declare function ExtensionProvider({ children, metadata, options }: ExtensionProviderProps): react_jsx_runtime.JSX.Element;
+
+export { type CreateExtensionContextOptions, type ExtensionContextReturn, ExtensionProvider, ExtensionProviderProps, createExtensionContext };