@djangocfg/ui-tools 2.1.415 → 2.1.417

package/dist/composer-registry/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Minimal imperative handle every text-editor surface implements so
+ * an external tool (voice dictation, command palette, AI suggestion)
+ * can read/write its text content without traversing React.
+ *
+ * Methods are optional so a host can register a partial handle
+ * (e.g. only `getValue` + `setValue`), and the caller checks before use.
+ */
+interface ComposerHandle {
+    /** Move keyboard focus into the composer's editable surface. */
+    focus: () => void;
+    /** Move the caret to the very end of the input. */
+    moveCursorToEnd?: () => void;
+    /** Read the current draft text. Voice dictation anchors partial
+     *  transcripts onto the user's already-typed prefix via this. */
+    getValue?: () => string;
+    /** Replace the current draft text. Voice dictation pushes interim
+     *  and final transcripts through this without owning a controlled
+     *  binding. */
+    setValue?: (value: string) => void;
+}
+/**
+ * `@djangocfg/ui-tools/composer-registry`
+ *
+ * Cross-tool bridge: the currently-active text composer's handle.
+ *
+ * Producer side (`@djangocfg/ui-tools/chat` and TipTap hosts):
+ *   register their composer's imperative handle via `attachComposer`.
+ *
+ * Consumer side (`@djangocfg/ui-tools/speech-recognition`):
+ *   reads the active handle via `useActiveComposer`/`getActiveComposer`
+ *   and pipes voice transcripts into it.
+ *
+ * Why this lives in its own subpath (not inside `chat`)
+ * ----------------------------------------------------
+ * `chat` and `speech-recognition` are sibling subpath exports. If the
+ * registry lived inside `chat`, then `speech-recognition` would have
+ * to reach into it via a cross-tool relative import — and under Vite
+ * dev's dependency optimizer that file ends up loaded TWICE (once via
+ * the `./chat` URL, once via the `./speech-recognition` relative-up
+ * URL), giving the producer and the consumer two separate `let active`
+ * slots. The active handle registered by chat would be invisible to
+ * speech-recognition (and vice versa).
+ *
+ * Putting the registry in its own dedicated subpath (a single tool
+ * that NEITHER chat nor speech-recognition cross-import — they both
+ * import this one as their dependency) means Vite resolves it from a
+ * single URL across the whole graph. One module instance, one shared
+ * `active` slot.
+ *
+ * Semantics: one active composer per realm. The most recent
+ * `registerComposer(handle)` wins; `registerComposer(null)` clears it.
+ */
+type Listener = (handle: ComposerHandle | null) => void;
+/** Set or replace the active composer handle. Pass `null` to clear. */
+declare function registerComposer(handle: ComposerHandle | null): void;
+/**
+ * Convenience for components: register on mount, unregister on
+ * unmount. Returns a cleanup function suitable for `useEffect`.
+ */
+declare function attachComposer(handle: ComposerHandle): () => void;
+/** Read the current active handle (no subscription). */
+declare function getActiveComposer(): ComposerHandle | null;
+/** Subscribe to handle changes; returns an unsubscribe fn. */
+declare function subscribeComposer(listener: Listener): () => void;
+/**
+ * React hook: re-renders the caller whenever the active composer
+ * changes. Built on `useSyncExternalStore` so concurrent rendering,
+ * SSR, and dev-mode strict-effects all behave correctly.
+ */
+declare function useActiveComposer(): ComposerHandle | null;
+
+export { type ComposerHandle, attachComposer, getActiveComposer, registerComposer, subscribeComposer, useActiveComposer };

package/dist/composer-registry/index.mjs

@@ -0,0 +1,39 @@
+import { __name } from '../chunk-PAWJFY3S.mjs';
+import { useCallback, useSyncExternalStore } from 'react';
+
+var active = null;
+var listeners = /* @__PURE__ */ new Set();
+function registerComposer(handle) {
+  active = handle;
+  for (const fn of listeners) fn(active);
+}
+__name(registerComposer, "registerComposer");
+function attachComposer(handle) {
+  registerComposer(handle);
+  return () => {
+    if (active === handle) registerComposer(null);
+  };
+}
+__name(attachComposer, "attachComposer");
+function getActiveComposer() {
+  return active;
+}
+__name(getActiveComposer, "getActiveComposer");
+function subscribeComposer(listener) {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+__name(subscribeComposer, "subscribeComposer");
+function useActiveComposer() {
+  const subscribe = useCallback((onChange) => {
+    return subscribeComposer(onChange);
+  }, []);
+  return useSyncExternalStore(subscribe, getActiveComposer, () => null);
+}
+__name(useActiveComposer, "useActiveComposer");
+
+export { attachComposer, getActiveComposer, registerComposer, subscribeComposer, useActiveComposer };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/composer-registry/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tools/integration/ComposerRegistry/index.ts"],"names":[],"mappings":";;;AA6DA,IAAI,MAAA,GAAgC,IAAA;AACpC,IAAM,SAAA,uBAAgB,GAAA,EAAc;AAG7B,SAAS,iBAAiB,MAAA,EAAqC;AACpE,EAAA,MAAA,GAAS,MAAA;AACT,EAAA,KAAA,MAAW,EAAA,IAAM,SAAA,EAAW,EAAA,CAAG,MAAM,CAAA;AACvC;AAHgB,MAAA,CAAA,gBAAA,EAAA,kBAAA,CAAA;AAST,SAAS,eAAe,MAAA,EAAoC;AACjE,EAAA,gBAAA,CAAiB,MAAM,CAAA;AACvB,EAAA,OAAO,MAAM;AACX,IAAA,IAAI,MAAA,KAAW,MAAA,EAAQ,gBAAA,CAAiB,IAAI,CAAA;AAAA,EAC9C,CAAA;AACF;AALgB,MAAA,CAAA,cAAA,EAAA,gBAAA,CAAA;AAQT,SAAS,iBAAA,GAA2C;AACzD,EAAA,OAAO,MAAA;AACT;AAFgB,MAAA,CAAA,iBAAA,EAAA,mBAAA,CAAA;AAKT,SAAS,kBAAkB,QAAA,EAAgC;AAChE,EAAA,SAAA,CAAU,IAAI,QAAQ,CAAA;AACtB,EAAA,OAAO,MAAM;AACX,IAAA,SAAA,CAAU,OAAO,QAAQ,CAAA;AAAA,EAC3B,CAAA;AACF;AALgB,MAAA,CAAA,iBAAA,EAAA,mBAAA,CAAA;AAYT,SAAS,iBAAA,GAA2C;AACzD,EAAA,MAAM,SAAA,GAAY,WAAA,CAAY,CAAC,QAAA,KAAyB;AACtD,IAAA,OAAO,kBAAkB,QAAQ,CAAA;AAAA,EACnC,CAAA,EAAG,EAAE,CAAA;AACL,EAAA,OAAO,oBAAA,CAAqB,SAAA,EAAW,iBAAA,EAAmB,MAAM,IAAI,CAAA;AACtE;AALgB,MAAA,CAAA,iBAAA,EAAA,mBAAA,CAAA","file":"index.mjs","sourcesContent":["'use client';\n\nimport { useCallback, useSyncExternalStore } from 'react';\n\n/**\n * Minimal imperative handle every text-editor surface implements so\n * an external tool (voice dictation, command palette, AI suggestion)\n * can read/write its text content without traversing React.\n *\n * Methods are optional so a host can register a partial handle\n * (e.g. only `getValue` + `setValue`), and the caller checks before use.\n */\nexport interface ComposerHandle {\n  /** Move keyboard focus into the composer's editable surface. */\n  focus: () => void;\n  /** Move the caret to the very end of the input. */\n  moveCursorToEnd?: () => void;\n  /** Read the current draft text. Voice dictation anchors partial\n   *  transcripts onto the user's already-typed prefix via this. */\n  getValue?: () => string;\n  /** Replace the current draft text. Voice dictation pushes interim\n   *  and final transcripts through this without owning a controlled\n   *  binding. */\n  setValue?: (value: string) => void;\n}\n\n/**\n * `@djangocfg/ui-tools/composer-registry`\n *\n * Cross-tool bridge: the currently-active text composer's handle.\n *\n * Producer side (`@djangocfg/ui-tools/chat` and TipTap hosts):\n *   register their composer's imperative handle via `attachComposer`.\n *\n * Consumer side (`@djangocfg/ui-tools/speech-recognition`):\n *   reads the active handle via `useActiveComposer`/`getActiveComposer`\n *   and pipes voice transcripts into it.\n *\n * Why this lives in its own subpath (not inside `chat`)\n * ----------------------------------------------------\n * `chat` and `speech-recognition` are sibling subpath exports. If the\n * registry lived inside `chat`, then `speech-recognition` would have\n * to reach into it via a cross-tool relative import — and under Vite\n * dev's dependency optimizer that file ends up loaded TWICE (once via\n * the `./chat` URL, once via the `./speech-recognition` relative-up\n * URL), giving the producer and the consumer two separate `let active`\n * slots. The active handle registered by chat would be invisible to\n * speech-recognition (and vice versa).\n *\n * Putting the registry in its own dedicated subpath (a single tool\n * that NEITHER chat nor speech-recognition cross-import — they both\n * import this one as their dependency) means Vite resolves it from a\n * single URL across the whole graph. One module instance, one shared\n * `active` slot.\n *\n * Semantics: one active composer per realm. The most recent\n * `registerComposer(handle)` wins; `registerComposer(null)` clears it.\n */\n\ntype Listener = (handle: ComposerHandle | null) => void;\n\nlet active: ComposerHandle | null = null;\nconst listeners = new Set<Listener>();\n\n/** Set or replace the active composer handle. Pass `null` to clear. */\nexport function registerComposer(handle: ComposerHandle | null): void {\n  active = handle;\n  for (const fn of listeners) fn(active);\n}\n\n/**\n * Convenience for components: register on mount, unregister on\n * unmount. Returns a cleanup function suitable for `useEffect`.\n */\nexport function attachComposer(handle: ComposerHandle): () => void {\n  registerComposer(handle);\n  return () => {\n    if (active === handle) registerComposer(null);\n  };\n}\n\n/** Read the current active handle (no subscription). */\nexport function getActiveComposer(): ComposerHandle | null {\n  return active;\n}\n\n/** Subscribe to handle changes; returns an unsubscribe fn. */\nexport function subscribeComposer(listener: Listener): () => void {\n  listeners.add(listener);\n  return () => {\n    listeners.delete(listener);\n  };\n}\n\n/**\n * React hook: re-renders the caller whenever the active composer\n * changes. Built on `useSyncExternalStore` so concurrent rendering,\n * SSR, and dev-mode strict-effects all behave correctly.\n */\nexport function useActiveComposer(): ComposerHandle | null {\n  const subscribe = useCallback((onChange: () => void) => {\n    return subscribeComposer(onChange);\n  }, []);\n  return useSyncExternalStore(subscribe, getActiveComposer, () => null);\n}\n"]}

package/dist/file-icon/index.d.cts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { LucideIcon } from 'lucide-react';
-import { b as TreeNode, g as TreeRowSlot } from '../types-j2vhn4Kv.cjs';
+import { T as TreeNode, b as TreeRowSlot } from '../slots-ClRpIzoh.cjs';
 import 'react';
 
 interface ResolveFolderIconOptions {

package/dist/file-icon/index.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { LucideIcon } from 'lucide-react';
-import { b as TreeNode, g as TreeRowSlot } from '../types-j2vhn4Kv.js';
+import { T as TreeNode, b as TreeRowSlot } from '../slots-ClRpIzoh.js';
 import 'react';
 
 interface ResolveFolderIconOptions {

package/dist/slots-ClRpIzoh.d.cts

@@ -0,0 +1,88 @@
+import { ReactNode, ComponentType } from 'react';
+
+type TreeItemId = string;
+/** A single node in the consumer's tree data. Generic over your payload. */
+interface TreeNode<T = unknown> {
+    id: TreeItemId;
+    data: T;
+    /** Inline children. Omit (and provide a `loadChildren`) for async loading. */
+    children?: TreeNode<T>[];
+    /**
+     * Set to `true` to mark a node as a folder even when its `children` array
+     * is empty (e.g. an unloaded async folder). Default: derived from
+     * `Array.isArray(children)`.
+     */
+    isFolder?: boolean;
+    /** Disable interaction. */
+    disabled?: boolean;
+}
+/**
+ * Internal flat-row representation used by the renderer + keyboard nav.
+ * Produced by `flattenTree`; consumed by `TreeRow`, the keyboard hook,
+ * and the type-ahead hook.
+ */
+interface FlatRow<T> {
+    node: TreeNode<T>;
+    level: number;
+    parentId: TreeItemId | null;
+    isFolder: boolean;
+    isExpanded: boolean;
+    isLoading: boolean;
+    hasError: boolean;
+    /** 1-based position among visible siblings (for `aria-posinset`). */
+    posInSet: number;
+    /** Count of visible siblings sharing this row's parent (for `aria-setsize`). */
+    setSize: number;
+}
+
+interface TreeRowRenderProps<T> {
+    node: TreeNode<T>;
+    level: number;
+    isSelected: boolean;
+    isExpanded: boolean;
+    isFocused: boolean;
+    isFolder: boolean;
+    isLoading: boolean;
+    isMatchingSearch: boolean;
+}
+type TreeRowSlot<T> = (props: TreeRowRenderProps<T>) => ReactNode;
+type TreeContextMenuSlot<T> = (props: TreeRowRenderProps<T>, trigger: ReactNode) => ReactNode;
+/**
+ * Declarative context-menu item. Pass `'separator'` (string) in place of an
+ * object to insert a `<ContextMenuSeparator />` between groups.
+ *
+ * For more advanced needs (submenus, checkbox items, custom JSX), drop down
+ * to `renderContextMenu` instead.
+ */
+interface TreeContextMenuAction<T> {
+    /** Stable React key. */
+    id: string;
+    label: ReactNode;
+    /** Lucide-style icon component. Rendered as `<icon className="size-4" />`. */
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    /** Right-aligned keyboard hint (e.g. `'⌘C'`, `'↵'`). Cosmetic. */
+    shortcut?: ReactNode;
+    /** Disable the item — still rendered, not selectable. */
+    disabled?: boolean;
+    /** Style as destructive (red). */
+    destructive?: boolean;
+    /** Click / Enter handler. Receives the row meta. */
+    onSelect: (props: TreeRowRenderProps<T>) => void;
+}
+type TreeContextMenuItem<T> = TreeContextMenuAction<T> | 'separator';
+/**
+ * Context passed to a `contextMenuActions` resolver. `row` is the row the
+ * user right-clicked. `selectedNodes` is the multi-selection at the
+ * moment the menu opens — when the right-clicked row was not in the
+ * selection, Tree first switches selection to that single row, so
+ * `selectedNodes` always contains the right-clicked node.
+ */
+interface TreeContextMenuActionsContext<T> extends TreeRowRenderProps<T> {
+    /** Multi-selection at the moment the menu opens. Always non-empty. */
+    selectedNodes: TreeNode<T>[];
+}
+type TreeContextMenuActionsResolver<T> = (ctx: TreeContextMenuActionsContext<T>) => TreeContextMenuItem<T>[] | null | undefined;
+
+export type { FlatRow as F, TreeNode as T, TreeItemId as a, TreeRowSlot as b, TreeContextMenuSlot as c, TreeContextMenuActionsResolver as d, TreeRowRenderProps as e, TreeContextMenuItem as f, TreeContextMenuAction as g, TreeContextMenuActionsContext as h };

package/dist/slots-ClRpIzoh.d.ts

@@ -0,0 +1,88 @@
+import { ReactNode, ComponentType } from 'react';
+
+type TreeItemId = string;
+/** A single node in the consumer's tree data. Generic over your payload. */
+interface TreeNode<T = unknown> {
+    id: TreeItemId;
+    data: T;
+    /** Inline children. Omit (and provide a `loadChildren`) for async loading. */
+    children?: TreeNode<T>[];
+    /**
+     * Set to `true` to mark a node as a folder even when its `children` array
+     * is empty (e.g. an unloaded async folder). Default: derived from
+     * `Array.isArray(children)`.
+     */
+    isFolder?: boolean;
+    /** Disable interaction. */
+    disabled?: boolean;
+}
+/**
+ * Internal flat-row representation used by the renderer + keyboard nav.
+ * Produced by `flattenTree`; consumed by `TreeRow`, the keyboard hook,
+ * and the type-ahead hook.
+ */
+interface FlatRow<T> {
+    node: TreeNode<T>;
+    level: number;
+    parentId: TreeItemId | null;
+    isFolder: boolean;
+    isExpanded: boolean;
+    isLoading: boolean;
+    hasError: boolean;
+    /** 1-based position among visible siblings (for `aria-posinset`). */
+    posInSet: number;
+    /** Count of visible siblings sharing this row's parent (for `aria-setsize`). */
+    setSize: number;
+}
+
+interface TreeRowRenderProps<T> {
+    node: TreeNode<T>;
+    level: number;
+    isSelected: boolean;
+    isExpanded: boolean;
+    isFocused: boolean;
+    isFolder: boolean;
+    isLoading: boolean;
+    isMatchingSearch: boolean;
+}
+type TreeRowSlot<T> = (props: TreeRowRenderProps<T>) => ReactNode;
+type TreeContextMenuSlot<T> = (props: TreeRowRenderProps<T>, trigger: ReactNode) => ReactNode;
+/**
+ * Declarative context-menu item. Pass `'separator'` (string) in place of an
+ * object to insert a `<ContextMenuSeparator />` between groups.
+ *
+ * For more advanced needs (submenus, checkbox items, custom JSX), drop down
+ * to `renderContextMenu` instead.
+ */
+interface TreeContextMenuAction<T> {
+    /** Stable React key. */
+    id: string;
+    label: ReactNode;
+    /** Lucide-style icon component. Rendered as `<icon className="size-4" />`. */
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    /** Right-aligned keyboard hint (e.g. `'⌘C'`, `'↵'`). Cosmetic. */
+    shortcut?: ReactNode;
+    /** Disable the item — still rendered, not selectable. */
+    disabled?: boolean;
+    /** Style as destructive (red). */
+    destructive?: boolean;
+    /** Click / Enter handler. Receives the row meta. */
+    onSelect: (props: TreeRowRenderProps<T>) => void;
+}
+type TreeContextMenuItem<T> = TreeContextMenuAction<T> | 'separator';
+/**
+ * Context passed to a `contextMenuActions` resolver. `row` is the row the
+ * user right-clicked. `selectedNodes` is the multi-selection at the
+ * moment the menu opens — when the right-clicked row was not in the
+ * selection, Tree first switches selection to that single row, so
+ * `selectedNodes` always contains the right-clicked node.
+ */
+interface TreeContextMenuActionsContext<T> extends TreeRowRenderProps<T> {
+    /** Multi-selection at the moment the menu opens. Always non-empty. */
+    selectedNodes: TreeNode<T>[];
+}
+type TreeContextMenuActionsResolver<T> = (ctx: TreeContextMenuActionsContext<T>) => TreeContextMenuItem<T>[] | null | undefined;
+
+export type { FlatRow as F, TreeNode as T, TreeItemId as a, TreeRowSlot as b, TreeContextMenuSlot as c, TreeContextMenuActionsResolver as d, TreeRowRenderProps as e, TreeContextMenuItem as f, TreeContextMenuAction as g, TreeContextMenuActionsContext as h };