@dyrected/admin 2.5.33 → 2.5.35

package/dist/components/forms/utils.d.ts

@@ -1,5 +1,9 @@
 import { Field as FieldSchema } from '@dyrected/sdk';
 import * as z from "zod";
+/**
+ * Normalises a field's `options` array to the canonical `{ label, value }` shape.
+ * Accepts either a shorthand string array or the full object form.
+ */
 export declare function normalizeOptions(options: string[] | {
     label: string;
     value: string;
@@ -7,10 +11,45 @@ export declare function normalizeOptions(options: string[] | {
     label: string;
     value: string;
 }[];
+/**
+ * Builds a Zod schema shape from a collection's field definitions.
+ * Used by the form engine to validate the edit form before submission.
+ *
+ * @param fields - Field definitions from the collection schema.
+ * @param isEdit - When `true`, password fields accept an empty string (no change).
+ * @returns A record of Zod validators keyed by field name, suitable for `z.object(shape)`.
+ */
 export declare function buildSchemaShape(fields: FieldSchema[], isEdit?: boolean): Record<string, z.ZodTypeAny>;
+/**
+ * Builds `react-hook-form` default values from a collection's field definitions
+ * and an existing document (or an empty object for new documents).
+ *
+ * Handles nested `object`, `array`, and `blocks` fields recursively.
+ * Relationship and image fields are normalised to their IDs.
+ * Password fields are always reset to `""` so they are never pre-filled.
+ *
+ * @param fields - Field definitions from the collection schema.
+ * @param defaults - Existing document data, or `{}` for a new document.
+ */
 export declare function buildDefaultValues(fields: FieldSchema[], defaults: any): any;
+/**
+ * Flattens a nested `react-hook-form` errors object into a list of
+ * `{ path, message }` pairs for rendering under individual fields.
+ *
+ * @param errors - The `formState.errors` object from `react-hook-form`.
+ * @param path - Dot-notation prefix accumulated during recursion (omit when calling externally).
+ * @returns A flat array of field path / error message pairs.
+ */
 export declare function getFlatErrors(errors: Record<string, unknown>, path?: string): {
     path: string;
     message: string;
 }[];
+/**
+ * Formats a dot-notation field path into a human-readable label.
+ * Array indices are converted to 1-based "Item N" labels.
+ *
+ * @example
+ * formatPath("address.street")      // → "Address > Street"
+ * formatPath("items.0.name")        // → "Items > Item 1 > Name"
+ */
 export declare function formatPath(path: string): string;

package/dist/index.d.ts

@@ -1,8 +1,20 @@
 import { DyrectedProviderProps } from './providers/dyrected-provider';
 export type { AdminComponents, AdminSchemas, CollectionListSlotProps, DashboardSlotProps, } from './types/admin-components';
+/**
+ * Props for the `<AdminUI />` embedded component.
+ *
+ * Use this when mounting the admin inside an existing React app or a
+ * framework-specific wrapper (Next.js, Nuxt, Astro, etc.).
+ */
 export interface AdminUIProps {
+    /** API key used to authenticate requests to the Dyrected backend. */
     apiKey?: string;
+    /**
+     * Base URL of the Dyrected backend API (e.g. `"https://example.com/dyrected"`).
+     * Defaults to `"/dyrected"` (same-origin).
+     */
     baseUrl?: string;
+    /** Site ID for multi-tenant deployments. Omit for single-site setups. */
     siteId?: string;
     /**
      * The base path where the admin is mounted in the host app.
@@ -22,22 +34,60 @@ export interface AdminUIProps {
      *   <AdminUI onNavigate={(path) => navigateTo('/admin' + path)} ... />
      */
     onNavigate?: (path: string) => void;
+    /**
+     * Set to `true` when the admin is rendered inside a host app shell
+     * (e.g. inside a dashboard layout). Adjusts internal spacing and
+     * removes the standalone top-bar.
+     */
     isEmbedded?: boolean;
+    /** Custom component overrides for fields, dashboard slots, and collection list views. */
     components?: DyrectedProviderProps['components'];
     initialToken?: string;
     defaultTechStack?: string;
 }
+/**
+ * The main admin UI component. Mount this inside your React app.
+ *
+ * Uses a `HashRouter` internally so it can be embedded without conflicting
+ * with the host app's router. If you need real URL history, use
+ * `renderAdminUI` with a custom router wrapper instead.
+ *
+ * @example
+ * ```tsx
+ * <AdminUI baseUrl="/dyrected" apiKey="my-key" isEmbedded />
+ * ```
+ */
 export declare function AdminUI({ apiKey, baseUrl, siteId, onNavigate, isEmbedded, components, initialToken, defaultTechStack, }: AdminUIProps): import("react/jsx-runtime").JSX.Element;
 /**
- * Renders the Admin UI into a DOM element.
- * Useful for non-React frameworks like Nuxt, Svelte, or Vanilla JS.
+ * Imperatively renders the Admin UI into a DOM element.
+ * Useful for non-React frameworks (Nuxt, Svelte, Vanilla JS, Web Components).
+ *
+ * @param container - The DOM element to mount into.
+ * @param props - Same props as `<AdminUI />`.
+ * @returns A cleanup function that unmounts the React root.
+ *
+ * @example
+ * ```ts
+ * const cleanup = renderAdminUI(document.getElementById('admin')!, { baseUrl: '/dyrected' });
+ * // Later:
+ * cleanup();
+ * ```
  */
 export declare function renderAdminUI(container: HTMLElement, props: AdminUIProps): () => void;
+/** Props for the `<AdminStandalone />` self-contained iframe variant. */
 export interface AdminStandaloneProps {
+    /** API key for authenticating backend requests. */
     apiKey: string;
+    /** Base URL of the Dyrected backend API. */
     baseUrl: string;
+    /** Site ID for multi-tenant deployments. */
     siteId?: string;
 }
+/**
+ * A fully self-contained admin UI that uses a `MemoryRouter`.
+ * Intended for iframe or self-hosted deployments where the admin owns
+ * the entire page and does not share URL history with a host app.
+ */
 export declare function AdminStandalone({ apiKey, baseUrl, siteId }: AdminStandaloneProps): import("react/jsx-runtime").JSX.Element;
 export { SetupPromptUI } from './pages/setup/setup-prompt';
 export type { SetupPromptProps } from './pages/setup/setup-prompt';

package/dist/index.mjs

@@ -136,6 +136,13 @@ function DyrectedProvider({ children, apiKey: initialApiKey, baseUrl: initialBas
 		children
 	});
 }
+/**
+* Returns the Dyrected admin context: the SDK client, current user, loaded
+* schemas, auth helpers, and registered component overrides.
+*
+* Must be called within a component tree wrapped by `DyrectedProvider`.
+* Throws if called outside of that context.
+*/
 var useDyrected = () => {
 	const context = useContext(DyrectedContext);
 	if (!context) throw new Error("useDyrected must be used within a DyrectedProvider");
@@ -156,9 +163,28 @@ function QueryProvider({ children }) {
 //#endregion
 //#region src/lib/utils.ts
 var customTwMerge = extendTailwindMerge({ prefix: "dy-" });
+/**
+* Merges Tailwind class names, resolving conflicts with the `dy-` prefix.
+* Drop-in replacement for `clsx` that handles Dyrected's scoped Tailwind build.
+*/
 function cn(...inputs) {
 	return customTwMerge(clsx(inputs));
 }
+/**
+* Resolves a media field value to an absolute URL.
+*
+* Handles three input shapes:
+* - A fully-qualified URL (`https://...`) — returned as-is.
+* - A root-relative path (`/uploads/...`) — origin prepended from `baseUrl`.
+* - A bare filename or storage path (`default/photo.jpg`) — prefixed with `/api/media/`.
+*
+* Bare strings that look like document IDs (no extension, no slash) are returned
+* as an empty string so they are not treated as media assets.
+*
+* @param val - A media field value: a URL string, storage path, or a document object with a `url` or `filename` property.
+* @param baseUrl - The Dyrected backend base URL, used to build the origin for relative paths.
+* @returns A fully-qualified URL string, or `""` if the value cannot be resolved.
+*/
 function getMediaUrl(val, baseUrl) {
 	if (!val) return "";
 	let baseOrigin = "";
@@ -193,9 +219,20 @@ function getMediaUrl(val, baseUrl) {
 }
 //#endregion
 //#region src/lib/admin-icons.ts
+/**
+* Type guard — returns `true` if `value` is a string that matches a known
+* Lucide icon name (i.e. a valid `AdminIconName`).
+*/
 function isAdminIconName(value) {
 	return typeof value === "string" && Object.prototype.hasOwnProperty.call(icons, value);
 }
+/**
+* Returns the Lucide icon component for `value` if it is a valid `AdminIconName`,
+* otherwise returns `fallback`.
+*
+* @param value - An untrusted value that may or may not be an icon name.
+* @param fallback - The icon to use when `value` is not a valid icon name.
+*/
 function resolveAdminIcon(value, fallback) {
 	return isAdminIconName(value) ? icons[value] : fallback;
 }
@@ -893,7 +930,7 @@ function Dashboard() {
 		user,
 		schemas: resolvedSchemas
 	};
-	const dashboardSlots = resolvedSchemas.admin?.components;
+	const dashboardSlots = resolvedSchemas?.admin?.components;
 	if (collections.length === 0 && globals.length === 0) return /* @__PURE__ */ jsxs("div", {
 		className: "dy-space-y-6",
 		children: [
@@ -1565,8 +1602,12 @@ function FilterBuilder({ schema, rules, onChange }) {
 //#endregion
 //#region src/lib/filter-rules.ts
 /**
-* Converts an array of FilterRules into a WhereClause.
-* All rules are ANDed together.
+* Converts an array of `FilterRule`s into a flat `WhereClause`.
+* All rules are AND'd together. When the same field appears more than once
+* the extra conditions are moved into the top-level `AND` array.
+*
+* @param rules - Active filter rules from the filter builder UI.
+* @returns A `WhereClause` ready to pass to `collection.find({ where })`.
 */
 function rulesToWhere(rules) {
 	if (!rules || rules.length === 0) return {};
@@ -1582,8 +1623,12 @@ function rulesToWhere(rules) {
 	return clause;
 }
 /**
-* Converts a flat WhereClause back into an array of FilterRules.
-* Best effort extraction for UI state.
+* Converts a flat `WhereClause` back into an array of `FilterRule`s.
+* Best-effort: nested `AND` conditions are unpacked; `OR` clauses are ignored.
+* Used to restore filter builder state from the URL `?where=` param.
+*
+* @param where - A `WhereClause` object, typically parsed from the URL.
+* @returns An array of `FilterRule`s suitable for rendering in the filter builder.
 */
 function whereToRules(where) {
 	if (!where || Object.keys(where).length === 0) return [];
@@ -2802,6 +2847,10 @@ var TabsContent = React$1.forwardRef(({ className, ...props }, ref) => /* @__PUR
 TabsContent.displayName = TabsPrimitive.Content.displayName;
 //#endregion
 //#region src/components/forms/utils.ts
+/**
+* Normalises a field's `options` array to the canonical `{ label, value }` shape.
+* Accepts either a shorthand string array or the full object form.
+*/
 function normalizeOptions(options) {
 	if (!options) return [];
 	return options.map((opt) => typeof opt === "string" ? {
@@ -2809,6 +2858,14 @@ function normalizeOptions(options) {
 		value: opt
 	} : opt);
 }
+/**
+* Builds a Zod schema shape from a collection's field definitions.
+* Used by the form engine to validate the edit form before submission.
+*
+* @param fields - Field definitions from the collection schema.
+* @param isEdit - When `true`, password fields accept an empty string (no change).
+* @returns A record of Zod validators keyed by field name, suitable for `z.object(shape)`.
+*/
 function buildSchemaShape(fields, isEdit = false) {
 	const shape = {};
 	fields.forEach((field) => {
@@ -2891,6 +2948,17 @@ function buildSchemaShape(fields, isEdit = false) {
 	});
 	return shape;
 }
+/**
+* Builds `react-hook-form` default values from a collection's field definitions
+* and an existing document (or an empty object for new documents).
+*
+* Handles nested `object`, `array`, and `blocks` fields recursively.
+* Relationship and image fields are normalised to their IDs.
+* Password fields are always reset to `""` so they are never pre-filled.
+*
+* @param fields - Field definitions from the collection schema.
+* @param defaults - Existing document data, or `{}` for a new document.
+*/
 function buildDefaultValues(fields, defaults) {
 	return fields.reduce((acc, field) => {
 		if (field.type === "join") {
@@ -2939,6 +3007,14 @@ function buildDefaultValues(fields, defaults) {
 		return acc;
 	}, {});
 }
+/**
+* Flattens a nested `react-hook-form` errors object into a list of
+* `{ path, message }` pairs for rendering under individual fields.
+*
+* @param errors - The `formState.errors` object from `react-hook-form`.
+* @param path - Dot-notation prefix accumulated during recursion (omit when calling externally).
+* @returns A flat array of field path / error message pairs.
+*/
 function getFlatErrors(errors, path = "") {
 	const result = [];
 	if (!errors) return result;
@@ -2959,6 +3035,14 @@ function getFlatErrors(errors, path = "") {
 	}
 	return result;
 }
+/**
+* Formats a dot-notation field path into a human-readable label.
+* Array indices are converted to 1-based "Item N" labels.
+*
+* @example
+* formatPath("address.street")      // → "Address > Street"
+* formatPath("items.0.name")        // → "Items > Item 1 > Name"
+*/
 function formatPath(path) {
 	return path.split(".").map((part) => {
 		if (/^\d+$/.test(part)) return `Item ${parseInt(part, 10) + 1}`;
@@ -11170,6 +11254,18 @@ function AdminRoutes({ onNavigate, isEmbedded = false }) {
 		] }) })]
 	}) });
 }
+/**
+* The main admin UI component. Mount this inside your React app.
+*
+* Uses a `HashRouter` internally so it can be embedded without conflicting
+* with the host app's router. If you need real URL history, use
+* `renderAdminUI` with a custom router wrapper instead.
+*
+* @example
+* ```tsx
+* <AdminUI baseUrl="/dyrected" apiKey="my-key" isEmbedded />
+* ```
+*/
 function AdminUI({ apiKey, baseUrl = "/dyrected", siteId, onNavigate, isEmbedded, components, initialToken, defaultTechStack }) {
 	const [mounted, setMounted] = useState(false);
 	useEffect(() => setMounted(true), []);
@@ -11201,14 +11297,30 @@ function AdminUI({ apiKey, baseUrl = "/dyrected", siteId, onNavigate, isEmbedded
 	});
 }
 /**
-* Renders the Admin UI into a DOM element. 
-* Useful for non-React frameworks like Nuxt, Svelte, or Vanilla JS.
+* Imperatively renders the Admin UI into a DOM element.
+* Useful for non-React frameworks (Nuxt, Svelte, Vanilla JS, Web Components).
+*
+* @param container - The DOM element to mount into.
+* @param props - Same props as `<AdminUI />`.
+* @returns A cleanup function that unmounts the React root.
+*
+* @example
+* ```ts
+* const cleanup = renderAdminUI(document.getElementById('admin')!, { baseUrl: '/dyrected' });
+* // Later:
+* cleanup();
+* ```
 */
 function renderAdminUI(container, props) {
 	const root = createRoot(container);
 	root.render(React.createElement(StrictMode, null, React.createElement(AdminUI, props)));
 	return () => root.unmount();
 }
+/**
+* A fully self-contained admin UI that uses a `MemoryRouter`.
+* Intended for iframe or self-hosted deployments where the admin owns
+* the entire page and does not share URL history with a host app.
+*/
 function AdminStandalone({ apiKey, baseUrl, siteId }) {
 	return /* @__PURE__ */ jsx("div", {
 		className: "dy-admin-ui dy-h-full",

package/dist/lib/admin-icons.d.ts

@@ -1,4 +1,15 @@
 import { LucideIcon } from 'lucide-react';
 import { AdminIconName } from '@dyrected/core';
+/**
+ * Type guard — returns `true` if `value` is a string that matches a known
+ * Lucide icon name (i.e. a valid `AdminIconName`).
+ */
 export declare function isAdminIconName(value: unknown): value is AdminIconName;
+/**
+ * Returns the Lucide icon component for `value` if it is a valid `AdminIconName`,
+ * otherwise returns `fallback`.
+ *
+ * @param value - An untrusted value that may or may not be an icon name.
+ * @param fallback - The icon to use when `value` is not a valid icon name.
+ */
 export declare function resolveAdminIcon(value: unknown, fallback: LucideIcon): LucideIcon;

package/dist/lib/filter-rules.d.ts

@@ -1,16 +1,32 @@
 import { WhereClause, WhereOperatorName } from '@dyrected/core';
+/**
+ * A single filter rule in the admin filter builder.
+ * An array of rules is AND'd together and converted to a `WhereClause`
+ * before being passed to `collection.find({ where })`.
+ */
 export interface FilterRule {
+    /** Field name from the collection schema. */
     field: string;
+    /** Comparison operator (e.g. `"equals"`, `"contains"`, `"gt"`). */
     operator: WhereOperatorName;
+    /** Comparison value. `undefined` when the operator is `"exists"`. */
     value: unknown;
 }
 /**
- * Converts an array of FilterRules into a WhereClause.
- * All rules are ANDed together.
+ * Converts an array of `FilterRule`s into a flat `WhereClause`.
+ * All rules are AND'd together. When the same field appears more than once
+ * the extra conditions are moved into the top-level `AND` array.
+ *
+ * @param rules - Active filter rules from the filter builder UI.
+ * @returns A `WhereClause` ready to pass to `collection.find({ where })`.
  */
 export declare function rulesToWhere(rules: FilterRule[]): WhereClause;
 /**
- * Converts a flat WhereClause back into an array of FilterRules.
- * Best effort extraction for UI state.
+ * Converts a flat `WhereClause` back into an array of `FilterRule`s.
+ * Best-effort: nested `AND` conditions are unpacked; `OR` clauses are ignored.
+ * Used to restore filter builder state from the URL `?where=` param.
+ *
+ * @param where - A `WhereClause` object, typically parsed from the URL.
+ * @returns An array of `FilterRule`s suitable for rendering in the filter builder.
  */
 export declare function whereToRules(where: WhereClause | undefined): FilterRule[];

package/dist/lib/utils.d.ts

@@ -1,3 +1,22 @@
 import { ClassValue } from 'clsx';
+/**
+ * Merges Tailwind class names, resolving conflicts with the `dy-` prefix.
+ * Drop-in replacement for `clsx` that handles Dyrected's scoped Tailwind build.
+ */
 export declare function cn(...inputs: ClassValue[]): string;
+/**
+ * Resolves a media field value to an absolute URL.
+ *
+ * Handles three input shapes:
+ * - A fully-qualified URL (`https://...`) — returned as-is.
+ * - A root-relative path (`/uploads/...`) — origin prepended from `baseUrl`.
+ * - A bare filename or storage path (`default/photo.jpg`) — prefixed with `/api/media/`.
+ *
+ * Bare strings that look like document IDs (no extension, no slash) are returned
+ * as an empty string so they are not treated as media assets.
+ *
+ * @param val - A media field value: a URL string, storage path, or a document object with a `url` or `filename` property.
+ * @param baseUrl - The Dyrected backend base URL, used to build the origin for relative paths.
+ * @returns A fully-qualified URL string, or `""` if the value cannot be resolved.
+ */
 export declare function getMediaUrl(val: string | any, baseUrl: string): string;

package/dist/providers/dyrected-provider.d.ts

@@ -28,5 +28,12 @@ export interface DyrectedProviderProps {
     components?: DyrectedContextType['components'];
 }
 export declare function DyrectedProvider({ children, apiKey: initialApiKey, baseUrl: initialBaseUrl, siteId: initialSiteId, initialToken, defaultTechStack, components }: DyrectedProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Returns the Dyrected admin context: the SDK client, current user, loaded
+ * schemas, auth helpers, and registered component overrides.
+ *
+ * Must be called within a component tree wrapped by `DyrectedProvider`.
+ * Throws if called outside of that context.
+ */
 export declare const useDyrected: () => DyrectedContextType;
 export {};

package/dist/types/admin-components.d.ts

@@ -1,23 +1,36 @@
 import { ComponentType } from 'react';
 import { AdminConfig, CollectionConfig, GlobalConfig } from '@dyrected/core';
 import { DyrectedClient, PaginatedResult } from '@dyrected/sdk';
+/** All collection and global schemas returned by the backend, plus optional admin config. */
 export interface AdminSchemas {
     collections: CollectionConfig[];
     globals: GlobalConfig[];
     admin?: AdminConfig;
 }
+/** Props injected into custom dashboard slot components. */
 export interface DashboardSlotProps {
+    /** Authenticated SDK client — use this to call any API. */
     client: DyrectedClient;
+    /** Currently logged-in user document, or `null` when unauthenticated. */
     user: Record<string, unknown> | null;
+    /** All schemas loaded from the backend. */
     schemas: AdminSchemas;
 }
+/** Props injected into custom collection list slot components. */
 export interface CollectionListSlotProps {
+    /** Authenticated SDK client. */
     client: DyrectedClient;
+    /** Currently logged-in user document, or `null` when unauthenticated. */
     user: Record<string, unknown> | null;
+    /** Schema config for the collection being rendered. */
     collection: CollectionConfig;
+    /** URL slug of the collection (e.g. `"posts"`). */
     collectionSlug: string;
+    /** Raw paginated response from the last `find()` call. */
     response: PaginatedResult<Record<string, unknown>> | undefined;
+    /** Unwrapped document array from `response`. */
     documents: Record<string, unknown>[];
+    /** `true` while the list query is in-flight. */
     isLoading: boolean;
     pagination: {
         page: number;
@@ -27,16 +40,47 @@ export interface CollectionListSlotProps {
         hasPrevPage: boolean;
     };
     permissions: {
+        /** Whether the current user may read documents in this collection. */
         canRead: boolean;
+        /** Whether the current user may create new documents. */
         canCreate: boolean;
     };
     urls: {
+        /** Admin URL for the collection list view. */
         collection: string;
+        /** Admin URL for the new-document form. */
         create: string;
     };
 }
+/**
+ * Custom component overrides passed to `<DyrectedAdmin />`.
+ *
+ * @example
+ * ```tsx
+ * <DyrectedAdmin
+ *   components={{
+ *     fields: { color: ColorPickerField },
+ *     dashboard: { analytics: AnalyticsWidget },
+ *     collectionList: { posts: PostsListView },
+ *   }}
+ * />
+ * ```
+ */
 export interface AdminComponents {
+    /**
+     * Custom field renderers keyed by field type name.
+     * A component registered here replaces the built-in renderer for every
+     * field whose `type` matches the key.
+     */
     fields?: Record<string, ComponentType<any>>;
+    /**
+     * Custom dashboard slot components keyed by a slot name of your choice.
+     * All registered components are rendered inside the dashboard page.
+     */
     dashboard?: Record<string, ComponentType<DashboardSlotProps>>;
+    /**
+     * Custom collection list slot components keyed by collection slug.
+     * The registered component replaces the entire list view for that collection.
+     */
     collectionList?: Record<string, ComponentType<CollectionListSlotProps>>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dyrected/admin",
-  "version": "2.5.33",
+  "version": "2.5.35",
   "type": "module",
   "files": [
     "dist"
@@ -62,8 +62,8 @@
     "tailwind-merge": "^3.5.0",
     "tailwindcss-animate": "^1.0.7",
     "zod": "^3.25.76",
-    "@dyrected/core": "^2.5.33",
-    "@dyrected/sdk": "^2.5.33"
+    "@dyrected/core": "^2.5.35",
+    "@dyrected/sdk": "^2.5.35"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.0.0",