@jini-ai/admin 0.4.2 → 0.4.4

package/dist/widgets/react/hooks/WidgetsPorts.hooks.d.ts

@@ -0,0 +1,270 @@
+import type { ComponentType, ReactNode } from 'react';
+import type { ScopedPorts } from '../../../core/module/types.js';
+import type { AdminWidgetType, WidgetTypeOption, WidgetSlugRedirectPath, WidgetsTranslate } from '../../models.js';
+export interface WidgetsSlots {
+    ConfigFields: ComponentType<{
+        widgetType: AdminWidgetType;
+        config: Record<string, unknown>;
+        onChange: (value: Record<string, unknown>) => void;
+        agentHandle?: string | undefined;
+        t?: WidgetsTranslate | undefined;
+    }>;
+    AddControl: ComponentType<{
+        triggerLabel: string;
+        onResolved: (id: string) => void;
+        agentHandle?: string | undefined;
+    }>;
+}
+/** Shared config UI/catalog/defaults and slug policy stay host-owned. Locale is presentation metadata. */
+export interface WidgetsReactOptions {
+    slots: WidgetsSlots;
+    widgetTypes: readonly WidgetTypeOption[];
+    defaultConfig: (type: AdminWidgetType) => Record<string, unknown>;
+    t?: WidgetsTranslate | undefined;
+    locale?: string | undefined;
+    slugRedirectPath?: WidgetSlugRedirectPath | undefined;
+    headerActions?: ReactNode | undefined;
+    /** Bind the host serverLabel owner when protocol values have a separate dictionary. */
+    statusLabel?: WidgetsTranslate | undefined;
+    navigationBase?: string | undefined;
+}
+export declare const WidgetsPortsContext: import("react").Context<ScopedPorts<{
+    readonly id: "widgets";
+    readonly requires: {
+        readonly widgetsApi: import("../../../core/module/token.js").AdminPortToken<import("../../ports.js").AdminWidgetsPort, "admin.widgets.api">;
+    };
+    readonly optional: {
+        readonly widgetsEvents: import("../../../core/module/token.js").AdminPortToken<import("../../ports.js").WidgetsEventsPort, "admin.widgets.events">;
+        readonly widgetsNavigation: import("../../../core/module/token.js").AdminPortToken<import("../../ports.js").WidgetsNavigationPort, "admin.widgets.navigation">;
+    };
+    readonly messages: {
+        readonly Back: "Back";
+        readonly "Widget type to create": "Widget type to create";
+        readonly Content: "Content";
+        readonly Text: "Text";
+        readonly "Social Links": "Social Links";
+        readonly "Collection list": "Collection list";
+        readonly Menu: "Menu";
+        readonly "Contact Form": "Contact Form";
+        readonly Widgets: "Widgets";
+        readonly "Widget Regions": "Widget Regions";
+        readonly "A region is a theme-declared placement area (e.g. \"header\", \"footer\", \"sidebar\"). Bind a region by its key to start placing widgets in it.": "A region is a theme-declared placement area (e.g. \"header\", \"footer\", \"sidebar\"). Bind a region by its key to start placing widgets in it.";
+        readonly "Binding\u2026": "Binding…";
+        readonly "Bind region": "Bind region";
+        readonly "No regions bound yet.": "No regions bound yet.";
+        readonly "Region key": "Region key";
+        readonly Placements: "Placements";
+        readonly Manage: "Manage";
+        readonly "Create reusable content blocks and place them into your theme's widget regions.": "Create reusable content blocks and place them into your theme's widget regions.";
+        readonly "Regions \u2192": "Regions →";
+        readonly "Add New": "Add New";
+        readonly "1 widget record in this workspace could not be read.": "1 widget record in this workspace could not be read.";
+        readonly "{n} widget records in this workspace could not be read.": "{n} widget records in this workspace could not be read.";
+        readonly "Show ids": "Show ids";
+        readonly "No widgets yet.": "No widgets yet.";
+        readonly "Create one above to get started.": "Create one above to get started.";
+        readonly Title: "Title";
+        readonly Type: "Type";
+        readonly Slug: "Slug";
+        readonly Status: "Status";
+        readonly Actions: "Actions";
+        readonly Trash: "Trash";
+        readonly "Move to trash?": "Move to trash?";
+        readonly "Move to trash": "Move to trash";
+        readonly "Move \"{title}\" to trash?": "Move \"{title}\" to trash?";
+        readonly Regions: "Regions";
+        readonly "Saving\u2026": "Saving…";
+        readonly Save: "Save";
+        readonly "Region:": "Region:";
+        readonly "Manage which widgets appear in this region and their order.": "Manage which widgets appear in this region and their order.";
+        readonly "No widgets placed in this region yet.": "No widgets placed in this region yet.";
+        readonly Enabled: "Enabled";
+        readonly "\u26A0 Broken reference": "⚠ Broken reference";
+        readonly "+ Add widget": "+ Add widget";
+        readonly "New widget": "New widget";
+        readonly "Edit widget": "Edit widget";
+        readonly "Configure this widget's title and settings.": "Configure this widget's title and settings.";
+        readonly "Widget title": "Widget title";
+        readonly "Type:": "Type:";
+        readonly "Region area": "Region area";
+        readonly "Inline embed": "Inline embed";
+        readonly "Used in 1 place:": "Used in 1 place:";
+        readonly "Used in {count} places:": "Used in {count} places:";
+        readonly "failed to load widget": "failed to load widget";
+        readonly "save failed": "save failed";
+        readonly "This widget changed since you loaded it, refresh and try again.": "This widget changed since you loaded it, refresh and try again.";
+        readonly "This region changed since you loaded it, refresh and try again.": "This region changed since you loaded it, refresh and try again.";
+        readonly "failed to load region": "failed to load region";
+        readonly "failed to load widgets": "failed to load widgets";
+        readonly "delete failed": "delete failed";
+        readonly "This item changed since you loaded it. Reload and try again.": "This item changed since you loaded it. Reload and try again.";
+        readonly "failed to load regions": "failed to load regions";
+        readonly "bind failed": "bind failed";
+        readonly "Loading widget\u2026": "Loading widget…";
+        readonly "No widget type specified.": "No widget type specified.";
+        readonly "Unknown widget type \"": "Unknown widget type \"";
+        readonly "Loading region\u2026": "Loading region…";
+        readonly "Move up": "Move up";
+        readonly "Move down": "Move down";
+        readonly Remove: "Remove";
+        readonly "Loading regions\u2026": "Loading regions…";
+        readonly "Loading widgets\u2026": "Loading widgets…";
+        readonly "Saved \u00B7 version {version}": "Saved · version {version}";
+    };
+    readonly pages: {
+        readonly library: {
+            readonly path: "/widgets";
+            readonly label: "Widgets";
+            readonly agentReachable: true;
+            readonly nav: {
+                readonly group: "Content";
+            };
+            readonly tabs: {};
+        };
+        readonly editor: {
+            readonly path: "/widgets/:widgetId";
+            readonly label: "Edit widget";
+            readonly agentReachable: true;
+            readonly tabs: {};
+        };
+        readonly regions: {
+            readonly path: "/widgets/regions";
+            readonly label: "Widget Regions";
+            readonly agentReachable: true;
+            readonly tabs: {};
+        };
+        readonly region: {
+            readonly path: "/widgets/regions/:regionKey";
+            readonly label: "Region:";
+            readonly agentReachable: true;
+            readonly tabs: {};
+        };
+    };
+}> | null>;
+export declare const WidgetsOptionsContext: import("react").Context<WidgetsReactOptions | null>;
+export declare function useWidgetsPorts(_required?: Record<string, never>, _optional?: Record<string, never>): ScopedPorts<{
+    readonly id: "widgets";
+    readonly requires: {
+        readonly widgetsApi: import("../../../core/module/token.js").AdminPortToken<import("../../ports.js").AdminWidgetsPort, "admin.widgets.api">;
+    };
+    readonly optional: {
+        readonly widgetsEvents: import("../../../core/module/token.js").AdminPortToken<import("../../ports.js").WidgetsEventsPort, "admin.widgets.events">;
+        readonly widgetsNavigation: import("../../../core/module/token.js").AdminPortToken<import("../../ports.js").WidgetsNavigationPort, "admin.widgets.navigation">;
+    };
+    readonly messages: {
+        readonly Back: "Back";
+        readonly "Widget type to create": "Widget type to create";
+        readonly Content: "Content";
+        readonly Text: "Text";
+        readonly "Social Links": "Social Links";
+        readonly "Collection list": "Collection list";
+        readonly Menu: "Menu";
+        readonly "Contact Form": "Contact Form";
+        readonly Widgets: "Widgets";
+        readonly "Widget Regions": "Widget Regions";
+        readonly "A region is a theme-declared placement area (e.g. \"header\", \"footer\", \"sidebar\"). Bind a region by its key to start placing widgets in it.": "A region is a theme-declared placement area (e.g. \"header\", \"footer\", \"sidebar\"). Bind a region by its key to start placing widgets in it.";
+        readonly "Binding\u2026": "Binding…";
+        readonly "Bind region": "Bind region";
+        readonly "No regions bound yet.": "No regions bound yet.";
+        readonly "Region key": "Region key";
+        readonly Placements: "Placements";
+        readonly Manage: "Manage";
+        readonly "Create reusable content blocks and place them into your theme's widget regions.": "Create reusable content blocks and place them into your theme's widget regions.";
+        readonly "Regions \u2192": "Regions →";
+        readonly "Add New": "Add New";
+        readonly "1 widget record in this workspace could not be read.": "1 widget record in this workspace could not be read.";
+        readonly "{n} widget records in this workspace could not be read.": "{n} widget records in this workspace could not be read.";
+        readonly "Show ids": "Show ids";
+        readonly "No widgets yet.": "No widgets yet.";
+        readonly "Create one above to get started.": "Create one above to get started.";
+        readonly Title: "Title";
+        readonly Type: "Type";
+        readonly Slug: "Slug";
+        readonly Status: "Status";
+        readonly Actions: "Actions";
+        readonly Trash: "Trash";
+        readonly "Move to trash?": "Move to trash?";
+        readonly "Move to trash": "Move to trash";
+        readonly "Move \"{title}\" to trash?": "Move \"{title}\" to trash?";
+        readonly Regions: "Regions";
+        readonly "Saving\u2026": "Saving…";
+        readonly Save: "Save";
+        readonly "Region:": "Region:";
+        readonly "Manage which widgets appear in this region and their order.": "Manage which widgets appear in this region and their order.";
+        readonly "No widgets placed in this region yet.": "No widgets placed in this region yet.";
+        readonly Enabled: "Enabled";
+        readonly "\u26A0 Broken reference": "⚠ Broken reference";
+        readonly "+ Add widget": "+ Add widget";
+        readonly "New widget": "New widget";
+        readonly "Edit widget": "Edit widget";
+        readonly "Configure this widget's title and settings.": "Configure this widget's title and settings.";
+        readonly "Widget title": "Widget title";
+        readonly "Type:": "Type:";
+        readonly "Region area": "Region area";
+        readonly "Inline embed": "Inline embed";
+        readonly "Used in 1 place:": "Used in 1 place:";
+        readonly "Used in {count} places:": "Used in {count} places:";
+        readonly "failed to load widget": "failed to load widget";
+        readonly "save failed": "save failed";
+        readonly "This widget changed since you loaded it, refresh and try again.": "This widget changed since you loaded it, refresh and try again.";
+        readonly "This region changed since you loaded it, refresh and try again.": "This region changed since you loaded it, refresh and try again.";
+        readonly "failed to load region": "failed to load region";
+        readonly "failed to load widgets": "failed to load widgets";
+        readonly "delete failed": "delete failed";
+        readonly "This item changed since you loaded it. Reload and try again.": "This item changed since you loaded it. Reload and try again.";
+        readonly "failed to load regions": "failed to load regions";
+        readonly "bind failed": "bind failed";
+        readonly "Loading widget\u2026": "Loading widget…";
+        readonly "No widget type specified.": "No widget type specified.";
+        readonly "Unknown widget type \"": "Unknown widget type \"";
+        readonly "Loading region\u2026": "Loading region…";
+        readonly "Move up": "Move up";
+        readonly "Move down": "Move down";
+        readonly Remove: "Remove";
+        readonly "Loading regions\u2026": "Loading regions…";
+        readonly "Loading widgets\u2026": "Loading widgets…";
+        readonly "Saved \u00B7 version {version}": "Saved · version {version}";
+    };
+    readonly pages: {
+        readonly library: {
+            readonly path: "/widgets";
+            readonly label: "Widgets";
+            readonly agentReachable: true;
+            readonly nav: {
+                readonly group: "Content";
+            };
+            readonly tabs: {};
+        };
+        readonly editor: {
+            readonly path: "/widgets/:widgetId";
+            readonly label: "Edit widget";
+            readonly agentReachable: true;
+            readonly tabs: {};
+        };
+        readonly regions: {
+            readonly path: "/widgets/regions";
+            readonly label: "Widget Regions";
+            readonly agentReachable: true;
+            readonly tabs: {};
+        };
+        readonly region: {
+            readonly path: "/widgets/regions/:regionKey";
+            readonly label: "Region:";
+            readonly agentReachable: true;
+            readonly tabs: {};
+        };
+    };
+}>;
+export declare function useWidgetsOptions(_required?: Record<string, never>, _optional?: Record<string, never>): {
+    t: WidgetsTranslate;
+    locale: string;
+    slots: WidgetsSlots;
+    widgetTypes: readonly WidgetTypeOption[];
+    defaultConfig: (type: AdminWidgetType) => Record<string, unknown>;
+    slugRedirectPath?: WidgetSlugRedirectPath | undefined;
+    headerActions?: ReactNode | undefined;
+    /** Bind the host serverLabel owner when protocol values have a separate dictionary. */
+    statusLabel?: WidgetsTranslate | undefined;
+    navigationBase?: string | undefined;
+};
+//# sourceMappingURL=WidgetsPorts.hooks.d.ts.map

package/dist/widgets/react/hooks/WidgetsPorts.hooks.js

@@ -0,0 +1,17 @@
+import { createContext, useContext } from 'react';
+import { widgetsEnglish } from '../../messages.en.js';
+export const WidgetsPortsContext = createContext(null);
+export const WidgetsOptionsContext = createContext(null);
+export function useWidgetsPorts(_required = {}, _optional = {}) {
+    const ports = useContext(WidgetsPortsContext);
+    if (!ports)
+        throw new Error('React scope unavailable: widgets');
+    return ports;
+}
+export function useWidgetsOptions(_required = {}, _optional = {}) {
+    const options = useContext(WidgetsOptionsContext);
+    if (!options)
+        throw new Error('React options unavailable: widgets');
+    return { ...options, t: options.t ?? widgetsEnglish, locale: options.locale ?? 'en' };
+}
+//# sourceMappingURL=WidgetsPorts.hooks.js.map

package/dist/widgets/react/hooks/navigation.hooks.d.ts

@@ -0,0 +1,9 @@
+import type { WidgetsNavigationPort } from '../../ports.js';
+/** Adapt the existing shell port; absent navigation leaves normal anchors available. */
+export declare function useWidgetsNavigate({ navigation, navigationBase }: {
+    navigation?: WidgetsNavigationPort | undefined;
+    navigationBase: string;
+}, _optional?: Record<string, never>): (path: string, options?: {
+    replace?: boolean;
+}) => void;
+//# sourceMappingURL=navigation.hooks.d.ts.map

package/dist/widgets/react/hooks/navigation.hooks.js

@@ -0,0 +1,6 @@
+import { useCallback } from 'react';
+/** Adapt the existing shell port; absent navigation leaves normal anchors available. */
+export function useWidgetsNavigate({ navigation, navigationBase }, _optional = {}) {
+    return useCallback((path, options) => { navigation?.navigate({ base: navigationBase, routePath: path }, options); }, [navigation, navigationBase]);
+}
+//# sourceMappingURL=navigation.hooks.js.map

package/dist/widgets/react/hooks/page-views.hooks.d.ts

@@ -0,0 +1,87 @@
+import { useWiredWidgetsLibrary } from './use-widgets-library.hooks.js';
+import { useWiredWidgetRegions } from './use-widget-regions.hooks.js';
+import { useWiredWidgetRegionEditor } from './use-widget-region-editor.hooks.js';
+/** Stable ids supply per-row handles because DataTable cells receive a row, not its index. */
+export declare function useWidgetsLibraryView({ useWidgetsLibraryHook }: {
+    useWidgetsLibraryHook?: typeof useWiredWidgetsLibrary | undefined;
+}, _optional?: Record<string, never>): {
+    rowHandleById: Map<string, string>;
+    widgets: import("../../models.js").AdminWidget[] | null;
+    error: string | null;
+    skippedCount: number;
+    skippedIds: string[];
+    createType: import("../../models.js").AdminWidgetType;
+    setCreateType: (type: import("../../models.js").AdminWidgetType) => void;
+    pendingTrash: import("../../models.js").AdminWidget | null;
+    trashing: boolean;
+    requestTrash: (widget: import("../../models.js").AdminWidget) => void;
+    confirmTrash: () => Promise<void>;
+    cancelTrash: () => void;
+    t: import("../../models.js").WidgetsTranslate;
+    locale: string;
+};
+export declare function useWidgetRegionsView({ useWidgetRegionsHook }: {
+    useWidgetRegionsHook?: typeof useWiredWidgetRegions | undefined;
+}, _optional?: Record<string, never>): {
+    rowHandleByKey: Map<string, string>;
+    regions: import("../../models.js").AdminWidgetRegionBinding[] | null;
+    error: string | null;
+    newRegionKey: string;
+    setNewRegionKey: (value: string) => void;
+    binding: boolean;
+    bind: () => Promise<void>;
+    t: import("../../models.js").WidgetsTranslate;
+};
+export declare function useWidgetRegionEditorView({ regionKey, useWidgetRegionEditorHook }: {
+    regionKey: string;
+    useWidgetRegionEditorHook?: typeof useWiredWidgetRegionEditor | undefined;
+}, _optional?: Record<string, never>): {
+    placementHandles: string[];
+    area: import("../../models.js").AdminWidgetArea | null;
+    placements: import("../../models.js").AdminWidgetPlacement[];
+    message: string | null;
+    error: string | null;
+    loading: boolean;
+    saving: boolean;
+    removeAt: (placementId: string) => void;
+    moveAt: (index: number, direction: -1 | 1) => void;
+    toggleEnabled: (placementId: string) => void;
+    addPlacement: (widgetInstanceId: string) => void;
+    save: () => Promise<void>;
+    t: import("../../models.js").WidgetsTranslate;
+    locale: string;
+};
+import type { MouseEvent } from 'react';
+import type { WidgetTypeOption } from '../../models.js';
+import { useWiredWidgetInstanceEditor } from './use-widget-instance-editor.hooks.js';
+/** The back-link cancellation also stops the host's document-level internal-link interceptor. */
+export declare function useWidgetInstanceEditorView({ widgetId, widgetType, widgetTypes, useWidgetInstanceEditorHook }: {
+    widgetId: string | null;
+    widgetType: string | null;
+    widgetTypes: readonly WidgetTypeOption[];
+    useWidgetInstanceEditorHook?: typeof useWiredWidgetInstanceEditor | undefined;
+}, _optional?: Record<string, never>): {
+    guard: import("../../rules.js").WidgetInstanceGuard | null;
+    onBackClick: (event: MouseEvent<HTMLAnchorElement>) => void;
+    isNew: boolean;
+    widget: import("../../models.js").AdminWidget | null;
+    whereUsed: import("../../models.js").AdminWidgetWhereUsed;
+    title: string;
+    setTitle: (title: string) => void;
+    config: Record<string, unknown>;
+    setConfig: (config: Record<string, unknown>) => void;
+    message: string | null;
+    error: string | null;
+    fieldErrors: Array<{
+        field: string;
+        reason: string;
+    }>;
+    loading: boolean;
+    saving: boolean;
+    widgetType: import("../../models.js").AdminWidgetType | null;
+    save: () => Promise<void>;
+    confirmLeave: import("@jini-ai/ui").DirtyGuard["confirmLeave"];
+    t: import("../../models.js").WidgetsTranslate;
+    locale: string;
+};
+//# sourceMappingURL=page-views.hooks.d.ts.map

package/dist/widgets/react/hooks/page-views.hooks.js

@@ -0,0 +1,30 @@
+import { buildAgentListHandles } from '@jini-ai/agentic';
+import { useWiredWidgetsLibrary } from './use-widgets-library.hooks.js';
+import { useWiredWidgetRegions } from './use-widget-regions.hooks.js';
+import { useWiredWidgetRegionEditor } from './use-widget-region-editor.hooks.js';
+/** Stable ids supply per-row handles because DataTable cells receive a row, not its index. */
+export function useWidgetsLibraryView({ useWidgetsLibraryHook = useWiredWidgetsLibrary }, _optional = {}) {
+    const state = useWidgetsLibraryHook();
+    const widgets = state.widgets ?? [];
+    const handles = buildAgentListHandles({ prefix: 'widgets-row', ids: widgets.map(w => w.id) });
+    return { ...state, rowHandleById: new Map(widgets.map((w, i) => [w.id, handles[i]])) };
+}
+export function useWidgetRegionsView({ useWidgetRegionsHook = useWiredWidgetRegions }, _optional = {}) {
+    const state = useWidgetRegionsHook();
+    const regions = state.regions ?? [];
+    const handles = buildAgentListHandles({ prefix: 'widget-regions-row', ids: regions.map(r => r.regionKey) });
+    return { ...state, rowHandleByKey: new Map(regions.map((r, i) => [r.regionKey, handles[i]])) };
+}
+export function useWidgetRegionEditorView({ regionKey, useWidgetRegionEditorHook = useWiredWidgetRegionEditor }, _optional = {}) {
+    const state = useWidgetRegionEditorHook(regionKey);
+    return { ...state, placementHandles: buildAgentListHandles({ prefix: 'widget-region-placement', ids: state.placements.map(p => p.placementId) }) };
+}
+import { widgetInstanceGuard } from '../../rules.js';
+import { useWiredWidgetInstanceEditor } from './use-widget-instance-editor.hooks.js';
+/** The back-link cancellation also stops the host's document-level internal-link interceptor. */
+export function useWidgetInstanceEditorView({ widgetId, widgetType, widgetTypes, useWidgetInstanceEditorHook = useWiredWidgetInstanceEditor }, _optional = {}) {
+    const state = useWidgetInstanceEditorHook({ widgetId, widgetType });
+    return { ...state, guard: widgetInstanceGuard({ ...state, types: widgetTypes }), onBackClick: (event) => { if (!state.confirmLeave())
+            event.preventDefault(); } };
+}
+//# sourceMappingURL=page-views.hooks.js.map

package/dist/widgets/react/hooks/use-widget-instance-editor.hooks.d.ts

@@ -0,0 +1,56 @@
+import type { AdminWidget, AdminWidgetType, AdminWidgetWhereUsed, WidgetsTranslate as Translate } from '../../models.js';
+import type { DirtyGuard } from '@jini-ai/ui/panel-kit';
+export interface WidgetInstanceEditorController {
+    isNew: boolean;
+    widget: AdminWidget | null;
+    whereUsed: AdminWidgetWhereUsed;
+    title: string;
+    setTitle: (title: string) => void;
+    config: Record<string, unknown>;
+    setConfig: (config: Record<string, unknown>) => void;
+    message: string | null;
+    error: string | null;
+    fieldErrors: Array<{
+        field: string;
+        reason: string;
+    }>;
+    loading: boolean;
+    saving: boolean;
+    /** The type this editor is configuring — the `?type=` query param while creating, the loaded
+     *  widget's own type once one exists. `null` when neither is available. */
+    widgetType: AdminWidgetType | null;
+    save: () => Promise<void>;
+    /** `useDirtyGuard`'s `confirmLeave` for the title/config pair — `WidgetInstanceEditor.tsx`'s back
+     *  link calls it before leaving (Opus themes+widgets review, OPEN item 2: this editor previously
+     *  had no unsaved-changes guard at all, unlike Posts/Pages). Always `true` with no prompt while
+     *  `widget` is `null` (a brand-new, not-yet-saved widget) — same "nothing loaded to compare
+     *  against yet" contract `useDirtyGuard`'s own doc describes; matches every other editor's
+     *  identical carve-out. */
+    confirmLeave: DirtyGuard["confirmLeave"];
+    /** Bound translator — `WidgetInstanceEditor.tsx`'s only source of UI copy; see this file's own
+     *  header. */
+    t: Translate;
+    /** The raw resolved locale — exposed only because `widgetTypeLabel` (`../rules.ts`) genuinely
+     *  needs it, not `t`. */
+    locale: string;
+}
+import type { AdminWidgetsPort } from '../../ports.js';
+import type { WidgetEditorParams, WidgetSlugRedirectPath } from '../../models.js';
+export type WidgetInstanceEditorHookProps = WidgetEditorParams;
+export declare function staleVersionMessage({ t }?: {
+    t?: Translate | undefined;
+}, _optional?: Record<string, never>): string;
+export declare function useWidgetInstanceEditor({ params, api, defaultConfig }: {
+    params: WidgetEditorParams;
+    api: AdminWidgetsPort;
+    defaultConfig: (type: AdminWidgetType) => Record<string, unknown>;
+}, { t, locale, navigate, slugRedirectPath }?: {
+    t?: Translate | undefined;
+    locale?: string | undefined;
+    navigate?: ((path: string, options?: {
+        replace?: boolean;
+    }) => void) | undefined;
+    slugRedirectPath?: WidgetSlugRedirectPath | undefined;
+}): WidgetInstanceEditorController;
+export declare function useWiredWidgetInstanceEditor(params: WidgetEditorParams): WidgetInstanceEditorController;
+//# sourceMappingURL=use-widget-instance-editor.hooks.d.ts.map

package/dist/widgets/react/hooks/use-widget-instance-editor.hooks.js

@@ -0,0 +1,38 @@
+import { useEffect, useRef, useCallback } from 'react';
+import { useDirtyGuard } from '@jini-ai/ui/panel-kit';
+import { useController } from '../../../core/react/use-controller.js';
+import { createWidgetInstanceEditorController } from '../../controllers/instance-editor.controller.js';
+import { widgetsEnglish } from '../../messages.en.js';
+import { widgetEntityKey } from '../../rules.js';
+import { useWidgetsPorts, useWidgetsOptions } from './WidgetsPorts.hooks.js';
+import { useWidgetsNavigate } from './navigation.hooks.js';
+export function staleVersionMessage({ t = widgetsEnglish } = {}, _optional = {}) { return t('This widget changed since you loaded it, refresh and try again.'); }
+export function useWidgetInstanceEditor({ params, api, defaultConfig }, { t = widgetsEnglish, locale = 'en', navigate, slugRedirectPath } = {}) {
+    const paramsRef = useRef(params);
+    // Saves compare with the latest rendered identity, before a route effect can run.
+    const renderedKey = useRef(widgetEntityKey({ params }));
+    renderedKey.current = widgetEntityKey({ params });
+    const latest = useRef({ t, navigate, slugRedirectPath });
+    latest.current = { t, navigate, slugRedirectPath };
+    const { controller, snapshot } = useController({ create: () => createWidgetInstanceEditorController({ api, params: paramsRef.current, defaultConfig }, {
+            getEntityKey: () => renderedKey.current, t: key => latest.current.t(key), navigate: (path, options) => latest.current.navigate?.(path, options),
+            slugRedirectPath: (base, id, item) => latest.current.slugRedirectPath?.(base, id, item) ?? null,
+        }), dependencies: [api, defaultConfig] }, { start: ({ controller }) => { void controller.load(); } });
+    useEffect(() => {
+        if (paramsRef.current.widgetId === params.widgetId && paramsRef.current.widgetType === params.widgetType)
+            return;
+        paramsRef.current = params;
+        controller?.setParams({ params });
+    }, [controller, params.widgetId, params.widgetType]);
+    const state = snapshot ?? { isNew: params.widgetId === null, widget: null, whereUsed: { count: 0, references: [] }, title: '', config: params.widgetId === null ? defaultConfig(params.widgetType ?? 'text') : {}, message: null, error: null, fieldErrors: [], loading: params.widgetId !== null, saving: false, widgetType: params.widgetId === null ? params.widgetType : undefined };
+    // New unsaved widgets have no original to compare with and leave without a prompt.
+    const { confirmLeave } = useDirtyGuard({ current: { title: state.title, config: state.config }, original: state.widget ? { title: state.widget.title, config: state.widget.config } : null }, { host: window, translate: key => key });
+    return { ...state, widgetType: state.widgetType, setTitle: title => controller?.setTitle({ title }), setConfig: config => controller?.setConfig({ config }), save: async () => { await controller?.save(); }, confirmLeave, t, locale };
+}
+export function useWiredWidgetInstanceEditor(params) {
+    const { widgetsApi: api, widgetsNavigation } = useWidgetsPorts();
+    const { t, locale, defaultConfig, slugRedirectPath, navigationBase = '/admin' } = useWidgetsOptions();
+    const navigate = useWidgetsNavigate({ navigation: widgetsNavigation, navigationBase });
+    return useWidgetInstanceEditor({ params, api, defaultConfig }, { t, locale, navigate, slugRedirectPath });
+}
+//# sourceMappingURL=use-widget-instance-editor.hooks.js.map

package/dist/widgets/react/hooks/use-widget-region-editor.hooks.d.ts

@@ -0,0 +1,32 @@
+import type { AdminWidgetArea, AdminWidgetPlacement, WidgetsTranslate as Translate } from '../../models.js';
+export interface WidgetRegionEditorController {
+    area: AdminWidgetArea | null;
+    placements: AdminWidgetPlacement[];
+    message: string | null;
+    error: string | null;
+    loading: boolean;
+    saving: boolean;
+    removeAt: (placementId: string) => void;
+    moveAt: (index: number, direction: -1 | 1) => void;
+    toggleEnabled: (placementId: string) => void;
+    addPlacement: (widgetInstanceId: string) => void;
+    save: () => Promise<void>;
+    /** Bound translator — `WidgetRegionEditor.tsx`'s only source of UI copy; see this file's own
+     *  header. */
+    t: Translate;
+    /** The raw resolved locale — exposed only because `widgetTypeLabel` (`../rules.ts`) needs it. */
+    locale: string;
+}
+import type { AdminWidgetsPort } from '../../ports.js';
+export declare function staleVersionMessage({ t }?: {
+    t?: Translate | undefined;
+}, _optional?: Record<string, never>): string;
+export declare function useWidgetRegionEditor({ regionKey, api }: {
+    regionKey: string;
+    api: AdminWidgetsPort;
+}, { t, locale }?: {
+    t?: Translate | undefined;
+    locale?: string | undefined;
+}): WidgetRegionEditorController;
+export declare function useWiredWidgetRegionEditor(regionKey: string): WidgetRegionEditorController;
+//# sourceMappingURL=use-widget-region-editor.hooks.d.ts.map

package/dist/widgets/react/hooks/use-widget-region-editor.hooks.js

@@ -0,0 +1,22 @@
+import { useEffect, useRef } from 'react';
+import { useController } from '../../../core/react/use-controller.js';
+import { createWidgetRegionEditorController } from '../../controllers/region-editor.controller.js';
+import { widgetsEnglish } from '../../messages.en.js';
+import { useWidgetsPorts, useWidgetsOptions } from './WidgetsPorts.hooks.js';
+export function staleVersionMessage({ t = widgetsEnglish } = {}, _optional = {}) { return t('This region changed since you loaded it, refresh and try again.'); }
+export function useWidgetRegionEditor({ regionKey, api }, { t = widgetsEnglish, locale = 'en' } = {}) {
+    const keyRef = useRef(regionKey), latestT = useRef(t);
+    latestT.current = t;
+    const { controller, snapshot } = useController({ create: () => createWidgetRegionEditorController({ api, regionKey: keyRef.current }, { t: key => latestT.current(key) }), dependencies: [api] }, { start: ({ controller }) => { void controller.load(); } });
+    useEffect(() => { if (keyRef.current !== regionKey) {
+        keyRef.current = regionKey;
+        controller?.setRegionKey({ regionKey });
+    } }, [controller, regionKey]);
+    return { ...(snapshot ?? { area: null, placements: [], message: null, error: null, loading: true, saving: false }), removeAt: placementId => controller?.removeAt({ placementId }), moveAt: (index, direction) => controller?.moveAt({ index, direction }), toggleEnabled: placementId => controller?.toggleEnabled({ placementId }), addPlacement: widgetInstanceId => controller?.addPlacement({ widgetInstanceId }), save: async () => { await controller?.save(); }, t, locale };
+}
+export function useWiredWidgetRegionEditor(regionKey) {
+    const { widgetsApi: api } = useWidgetsPorts();
+    const { t, locale } = useWidgetsOptions();
+    return useWidgetRegionEditor({ regionKey, api }, { t, locale });
+}
+//# sourceMappingURL=use-widget-region-editor.hooks.js.map

package/dist/widgets/react/hooks/use-widget-regions.hooks.d.ts

@@ -0,0 +1,23 @@
+import type { AdminWidgetRegionBinding, WidgetsTranslate as Translate } from '../../models.js';
+export interface WidgetRegionsController {
+    /** `null` until the initial load settles — the caller renders a loading state. */
+    regions: AdminWidgetRegionBinding[] | null;
+    error: string | null;
+    newRegionKey: string;
+    setNewRegionKey: (value: string) => void;
+    binding: boolean;
+    bind: () => Promise<void>;
+    /** Bound translator — `WidgetRegions.tsx`'s only source of UI copy; see this file's own header. */
+    t: Translate;
+}
+import type { AdminWidgetsPort, WidgetsEventsPort } from '../../ports.js';
+export declare function useWidgetRegions({ api }: {
+    api: AdminWidgetsPort;
+}, { t, locale, events, navigate }?: {
+    t?: Translate | undefined;
+    locale?: string | undefined;
+    events?: WidgetsEventsPort | undefined;
+    navigate?: ((path: string) => void) | undefined;
+}): WidgetRegionsController;
+export declare function useWiredWidgetRegions(): WidgetRegionsController;
+//# sourceMappingURL=use-widget-regions.hooks.d.ts.map

package/dist/widgets/react/hooks/use-widget-regions.hooks.js

@@ -0,0 +1,22 @@
+import { useEffect, useRef } from 'react';
+import { useController } from '../../../core/react/use-controller.js';
+import { createWidgetRegionsController } from '../../controllers/regions.controller.js';
+import { widgetsEnglish } from '../../messages.en.js';
+import { WIDGETS_REGIONS_RESOURCE } from '../../rules.js';
+import { useWidgetsPorts, useWidgetsOptions } from './WidgetsPorts.hooks.js';
+export function useWidgetRegions({ api }, { t = widgetsEnglish, locale = 'en', events, navigate } = {}) {
+    const latest = useRef({ t, navigate });
+    latest.current = { t, navigate };
+    const { controller, snapshot } = useController({ create: () => createWidgetRegionsController({ api }, { t: key => latest.current.t(key), navigate: path => latest.current.navigate?.(path) }), dependencies: [api] }, { start: ({ controller }) => { void controller.load(); } });
+    useEffect(() => { if (!controller)
+        return; return events?.subscribe({ resource: WIDGETS_REGIONS_RESOURCE, onRefresh: () => { void controller.load(); } }); }, [controller, events]);
+    return { ...(snapshot ?? { regions: null, error: null, newRegionKey: '', binding: false }), setNewRegionKey: value => controller?.setNewRegionKey({ value }), bind: async () => { await controller?.bind(); }, t };
+}
+export function useWiredWidgetRegions() {
+    const { widgetsApi: api, widgetsEvents: events, widgetsNavigation } = useWidgetsPorts();
+    const { t, locale, navigationBase = '/admin' } = useWidgetsOptions();
+    const navigate = useWidgetsNavigate({ navigation: widgetsNavigation, navigationBase });
+    return useWidgetRegions({ api }, { t, locale, events, navigate });
+}
+import { useWidgetsNavigate } from './navigation.hooks.js';
+//# sourceMappingURL=use-widget-regions.hooks.js.map