@terra-symposium/docs 0.1.78 → 0.1.80

package/lib-dist/components/terra/pages/docs/_toolbar.js

@@ -1,4 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * src/components/terra/pages/docs/_toolbar.tsx
+ */
 // @ts-nocheck -- source-preserving extraction; public host contracts are typed in src/host.ts.
 /**
  * astro/src/pages/docs/_toolbar.tsx
@@ -9,41 +12,31 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 IMPORTS
 //////////////////////////////////////////////////*/
 // API
-import { clearTransition, setTransition, useAtom } from '../../../../lib/terra/docs/state.js';
 import { $attachmentFilter } from '../../../../lib/terra/docs/attachments.js';
-import { codeViewOf } from '../../../../lib/terra/docs/editor-dom.js';
-import { FindReplace } from './_toolbar-find-replace.js';
-import { toolbarFocusValue } from '../../../../lib/terra/docs/toolbar.js';
-import { isDocBody } from '../../../../lib/terra/runtime/types.js';
 import { $createHeadingNode } from '@lexical/rich-text';
 import { $createParagraphNode, $getNearestNodeFromDOMNode, $isElementNode } from 'lexical';
 import { actions } from '../../../../lib/terra/runtime/action-proxy.js';
-import { dirname, docsRootPath, toPascal } from '../../../../lib/terra/runtime/shared.js';
+import { clearTransition, setTransition, useAtom } from '../../../../lib/terra/docs/state.js';
 import { cn, notify } from '../../../../lib/terra/runtime/runtime.js';
+import { codeViewOf } from '../../../../lib/terra/docs/editor-dom.js';
 import { components as repoComponents } from '../../../../lib/terra/custom-components.js';
+import { dirname, docsRootPath, toPascal } from '../../../../lib/terra/runtime/shared.js';
+import { getDocsHostAdapter } from '../../../../lib/host-runtime.js';
+import { isDocBody } from '../../../../lib/terra/runtime/types.js';
 import { redo, redoDepth, undo, undoDepth } from '@codemirror/commands';
 import { stringifyDocBody } from '../../../../lib/terra/runtime/content/document-markdown.js';
 import { toast } from 'sonner';
+import { toolbarFocusValue } from '../../../../lib/terra/docs/toolbar.js';
 import { useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
-import { getDocsHostAdapter } from '../../../../lib/host-runtime.js';
 // COMPONENTS
 import * as TerraQualityRegex from '../../../../lib/terra/regex.mjs';
 import React from 'react';
-import { TextTooltip, TooltipProvider } from '@terra-symposium/styling/ui';
 import { ArrowUpRight as PopOutIcon, CaretDown as CaretDownIcon, DataShare as ShareIcon, Image as ImageIcon, Link as LinkIcon, ListBulleted as BulletListIcon, ListNumbered as NumberListIcon, Paste as PasteIcon, Redo as RedoIcon, RepoSourceCode as ModuleIcon, Search as SearchIcon, Task as CheckListIcon, TextBold as BoldIcon, TextFont as TextFontIcon, TextItalic as ItalicIcon, TextStrikethrough as StrikethroughIcon, TextUnderline as UnderlineIcon, Undo as UndoIcon, } from '@carbon/icons-react';
-import { Button as UiButton } from '@terra-symposium/styling/ui';
-import { ButtonGroup } from '@terra-symposium/styling/ui';
+import { Button as UiButton, ButtonGroup, Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, Input, Label, Popover, PopoverContent, PopoverTrigger, SearchEmpty, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectSeparator, SelectTrigger, SelectValue, TextTooltip, ToggleGroup, ToggleGroupItem, TooltipProvider, } from '@terra-symposium/styling/ui';
 import { CodeBlock } from '../../editor/docs/_CodeBlock.js';
-import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, } from '@terra-symposium/styling/ui';
-import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, } from '@terra-symposium/styling/ui';
 import { EditStateCtx } from '../../../../lib/terra/docs/state.js';
 import { ErrorBoundary } from '../../ui.js';
-import { Input } from '@terra-symposium/styling/ui';
-import { Label } from '@terra-symposium/styling/ui';
-import { Popover, PopoverContent, PopoverTrigger } from '@terra-symposium/styling/ui';
-import { SearchEmpty } from '@terra-symposium/styling/ui';
-import { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectSeparator, SelectTrigger, SelectValue, } from '@terra-symposium/styling/ui';
-import { ToggleGroup, ToggleGroupItem } from '@terra-symposium/styling/ui';
+import { FindReplace } from './_toolbar-find-replace.js';
 // DATA
 import { ATTCH_TYPES } from '../../../../lib/terra/docs/attachments.js';
 import { DOCS_BLOCK_ICONS } from './_icons.js';
@@ -68,11 +61,13 @@ const MENU_WIDTH_CLASS = 'w-56';
 HELPERS
 //////////////////////////////////////////////////*/
 /**
- * Handles code offset.
+ * Measures the visible text offset of a DOM position within the active editor.
  *
- * @param content - Docs content containing the target block.
- * @param node - Block node being transformed by the toolbar action.
- * @param value - Replacement value supplied by the toolbar control.
+ * @param content Editor element whose rendered text supplies the offset basis.
+ * @param node DOM node containing the position being measured.
+ * @param val Offset within `node` at which the range should end.
+ *
+ * @return Character count before the position, or the full editor text length when the node is outside it.
  */
 const codeOffset = (content, node, val) => {
     if (!content.contains(node))
@@ -82,14 +77,6 @@ const codeOffset = (content, node, val) => {
     range.setEnd(node, val);
     return range.toString().length;
 };
-/**
- * Derives a clean, human-readable label from a raw filename or URL.
- *
- * @param {string} v - The raw filename or path string.
- * @param {string} fallback - The default label if extraction fails.
- *
- * @return {string} The formatted, capitalized label.
- */
 /**
  * Prevents the active selection range from being lost when clicking toolbar buttons.
  *
@@ -152,12 +139,18 @@ function looksLikeJsonBlob(val) {
     // prettier-ignore
     return ['{}', '[]'].some(p => v.startsWith(p[0]) && v.endsWith(p[1])) && v.length > 80;
 }
-/*//////////////////////////////////////////////////
-COMPONENTS
-//////////////////////////////////////////////////*/
-const Button = React.forwardRef(function Button({ children: c, className: v, disabled: d, lbl: l, shortcut: s, onClick: o, onMouseDown: r, active: a, ...p }, x) {
+const Button = React.forwardRef(
+/**
+ * Renders the toolbar's compact button with its label and optional shortcut hint.
+ *
+ * @param props Button content, label, shortcut, active state, and native button attributes.
+ * @param ref Forwarded reference attached to the rendered button.
+ * @returns The styled button wrapped in its tooltip.
+ */
+function Button(props, ref) {
+    const { children: c, className: v, disabled: d, lbl: l, shortcut: s, onClick: o, onMouseDown: r, active: a, ...p } = props;
     void a;
-    return (_jsx(TextTooltip, { content: s ? `${l} (${s})` : l, side: "top", align: "center", delayDuration: 400, children: _jsx(UiButton, { ref: x, variant: "ghost", size: "xs", "aria-label": l, disabled: d, onClick: o, onMouseDown: r, className: cn('inline-flex h-6 !p-0.5 shadow-none', v), ...p, children: c }) }));
+    return (_jsx(TextTooltip, { content: s ? `${l} (${s})` : l, side: "top", align: "center", delayDuration: 400, children: _jsx(UiButton, { ref: ref, variant: "ghost", size: "xs", "aria-label": l, disabled: d, onClick: o, onMouseDown: r, className: cn('inline-flex h-6 !p-0.5 shadow-none', v), ...p, children: c }) }));
 });
 Button.displayName = 'Button';
 /**
@@ -181,18 +174,15 @@ function Mode({ mode, onModeChange, disabled, editable, size = 'xs', }) {
             onModeChange(n);
         }, children: [_jsx(SelectTrigger, { "aria-label": "Mode", width: "fit", children: _jsx(SelectValue, { placeholder: "Mode" }) }), _jsx(SelectContent, { align: 'start', children: (editable ? ['view', 'edit', 'attachments'] : ['view', 'attachments']).map(o => _jsx(SelectItem, { value: o, children: o[0].toUpperCase() + o.slice(1) }, o)) })] }));
 }
-/**
- * Renders Docs-specific controls beside a content editor toolbar.
- *
- * Formatting and content insertion remain editor-owned; these controls manage
- * the document shell's mode and persistence state.
- *
- * @param props - Docs toolbar state and current mode.
- *
- * @return The mode, history, save, or version actions supported by the active Docs editor toolbar.
- */
 const TOOLBAR_COMPONENTS = {
-    DocsToolbarActions({ activeMode, editable, size = 'xs', toolbar, }) {
+    /**
+     * Adds Docs-specific mode, history, save, and version controls beside an editor toolbar.
+     *
+     * @param props Active mode, editability, control size, and toolbar state.
+     *
+     * @return Supported Docs actions, or `null` when the host is read-only.
+     */
+    DocsToolbarActions({ activeMode: aMode, editable, size = 'xs', toolbar, }) {
         const edit = useContext(EditStateCtx);
         const [versions, setVersions] = useState([]);
         const [historyOpen, setHistoryOpen] = useState(false);
@@ -224,9 +214,9 @@ const TOOLBAR_COMPONENTS = {
                     if (live && Array.isArray(data))
                         setVersions(data);
                 }
-                catch (error) {
-                    console.error('[Toolbar:versions] load-failed', { path, error });
-                    toast.error(error instanceof Error ? error.message : 'Failed to load doc versions.');
+                catch (err) {
+                    console.error('[Toolbar:versions] load-failed', { path, error: err });
+                    toast.error(err instanceof Error ? err.message : 'Failed to load doc versions.');
                 }
             })();
             return () => {
@@ -237,6 +227,13 @@ const TOOLBAR_COMPONENTS = {
             if (historyOpen && !selectedVersionId && versions[0])
                 setSelectedVersionId(versions[0].savedAt);
         }, [historyOpen, selectedVersionId, versions]);
+        /**
+         * Saves the current document while preventing the toolbar form's default submission.
+         *
+         * @param event Form event whose browser submission must be cancelled.
+         *
+         * @return A promise that settles after the save callback finishes or reports an error.
+         */
         const save = async (event) => {
             event.preventDefault();
             if (!toolbar?.save)
@@ -244,24 +241,31 @@ const TOOLBAR_COMPONENTS = {
             try {
                 await Promise.resolve(toolbar.save());
             }
-            catch (error) {
-                console.error('[Docs:save] failed', error);
-                toast.error(error instanceof Error ? error.message : 'Unable to save document.');
+            catch (err) {
+                console.error('[Docs:save] failed', err);
+                toast.error(err instanceof Error ? err.message : 'Unable to save document.');
             }
         };
         useEffect(() => {
-            if (activeMode === 'view')
+            if (aMode === 'view')
                 return;
+            /**
+             * Saves the document when the user presses the platform save shortcut.
+             *
+             * @param event Keyboard event dispatched by the document.
+             *
+             * @return Nothing; matching shortcuts delegate to the save handler.
+             */
             const onKeyDown = (event) => {
                 if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 's')
                     void save(event);
             };
             document.addEventListener('keydown', onKeyDown);
             return () => document.removeEventListener('keydown', onKeyDown);
-        }, [activeMode, toolbar]);
+        }, [aMode, toolbar]);
         if (!editable)
             return null;
-        return (_jsx(TooltipProvider, { children: _jsxs("div", { className: "flex items-center gap-1", "data-docs-toolbar-actions": true, children: [_jsx(Mode, { editable: editable, mode: activeMode, size: size, disabled: !toolbar, onModeChange: (mode) => {
+        return (_jsx(TooltipProvider, { children: _jsxs("div", { className: "flex items-center gap-1", "data-docs-toolbar-actions": true, children: [_jsx(Mode, { editable: editable, mode: aMode, size: size, disabled: !toolbar, onModeChange: (mode) => {
                             if (!toolbar)
                                 return;
                             void toolbar.setMode(mode).catch((error) => {
@@ -269,7 +273,7 @@ const TOOLBAR_COMPONENTS = {
                                 toast.error(error instanceof Error ? error.message : 'Failed to change mode.');
                                 clearTransition();
                             });
-                        } }), activeMode === 'edit' && (_jsxs(ButtonGroup, { children: [_jsx(TextTooltip, { content: "Save (\u2318S)", side: "top", align: "center", delayDuration: 400, children: _jsx(UiButton, { size: size, disabled: !toolbar || !toolbar.dirty, loading: toolbar?.busy === 'saving', onMouseDown: preserveSel, onClick: (event) => void save(event), children: "Save" }) }), historyEnabled && (_jsx(TextTooltip, { content: "Version History", side: "top", align: "center", delayDuration: 400, children: _jsx(UiButton, { size: size, className: "px-0.5", disabled: !toolbar, "aria-label": "Version History", onMouseDown: preserveSel, onClick: () => {
+                        } }), aMode === 'edit' && (_jsxs(ButtonGroup, { children: [_jsx(TextTooltip, { content: "Save (\u2318S)", side: "top", align: "center", delayDuration: 400, children: _jsx(UiButton, { size: size, disabled: !toolbar || !toolbar.dirty, loading: toolbar?.busy === 'saving', onMouseDown: preserveSel, onClick: (event) => void save(event), children: "Save" }) }), historyEnabled && (_jsx(TextTooltip, { content: "Version History", side: "top", align: "center", delayDuration: 400, children: _jsx(UiButton, { size: size, className: "px-0.5", disabled: !toolbar, "aria-label": "Version History", onMouseDown: preserveSel, onClick: () => {
                                         if (versions.length > 0 && !selectedVersionId)
                                             setSelectedVersionId(versions[0].savedAt);
                                         setHistoryOpen(true);
@@ -311,6 +315,7 @@ const TOOLBAR_COMPONENTS = {
             let frame = 0;
             /**
              * Handles sync.
+             *
              */
             const sync = () => {
                 const view = codeViewOf();
@@ -322,6 +327,7 @@ const TOOLBAR_COMPONENTS = {
             sync();
             /**
              * Handles refresh.
+             *
              */
             const refresh = () => {
                 cancelAnimationFrame(frame);
@@ -664,10 +670,12 @@ const TOOLBAR_COMPONENTS = {
         }, [search.query, search.tree]);
         // 5. EMBED OR CREATE LEAF
         /**
-         * Handles embed.
+         * Creates a page when requested and links the destination into the current document.
+         *
+         * @param tgtPath Existing destination path, or the initial path for a new page.
+         * @param isNew Whether a new page should be created before linking it.
          *
-         * @param targetPath - Destination path for the moved or renamed document.
-         * @param isNew - Whether the destination represents a newly created document.
+         * @return A promise that settles after the page link is inserted and the editor is restored.
          */
         const embed = async (tgtPath, isNew = false) => {
             let finalPath = tgtPath;
@@ -904,6 +912,7 @@ const TOOLBAR_COMPONENTS = {
             sync();
             /**
              * Handles refresh.
+             *
              */
             const refresh = () => {
                 cancelAnimationFrame(frame);
@@ -1065,6 +1074,7 @@ const TOOLBAR_COMPONENTS = {
         useEffect(() => {
             /**
              * Handles sync.
+             *
              */
             const sync = () => {
                 const view = codeViewOf();
@@ -1090,6 +1100,11 @@ const TOOLBAR_COMPONENTS = {
         const saving = toolbar?.busy ?? null;
         const dirty = toolbar?.dirty ?? false;
         const publishDraft = getDocsHostAdapter()?.publishDraft;
+        /**
+         * Saves pending edits and publishes the active document through the host adapter.
+         *
+         * @return A promise that settles after publishing or reports a user-facing error.
+         */
         const publish = async () => {
             if (!publishDraft || !toolbar?.path)
                 return;
@@ -1099,8 +1114,8 @@ const TOOLBAR_COMPONENTS = {
                 await publishDraft(toolbar.path);
                 toast.success('Published.');
             }
-            catch (error) {
-                toast.error(error instanceof Error ? error.message : 'Unable to publish document.');
+            catch (err) {
+                toast.error(err instanceof Error ? err.message : 'Unable to publish document.');
             }
         };
         useEffect(() => {
@@ -1207,9 +1222,11 @@ const TOOLBAR_COMPONENTS = {
         };
         const insert = toolbar?.insert ?? adapter?.insert;
         /**
-         * Handles json command.
+         * Dispatches a structured text command when the editor is in edit mode.
          *
          * @param detail - Toolbar detail describing the requested document update.
+         *
+         * @return `true` after dispatching in edit mode, or `false` when the editor is read-only.
          */
         const jsonCmd = (detail) => {
             if (mode !== 'edit')
@@ -1218,10 +1235,12 @@ const TOOLBAR_COMPONENTS = {
             return true;
         };
         /**
-         * Handles json block.
+         * Creates a Portable Text block with a fresh key and the supplied field data.
+         *
+         * @param _type Portable Text block type assigned by the caller.
+         * @param val Block fields copied into the new object.
          *
-         * @param _type - Sanity field type associated with the value.
-         * @param value - Field value being normalized for the toolbar.
+         * @return A block object with a new `_key`, the requested type, and supplied fields.
          */
         const jsonBlock = (_type, val) => ({
             _key: crypto.randomUUID(),
@@ -1235,7 +1254,7 @@ const TOOLBAR_COMPONENTS = {
          * @param fallback - Value passed to the helper.
          * @param isInline - Value passed to the helper.
          *
-         * @returns safe Sel.
+         * @return safe Sel.
          */
         const sSel = (fallback, isInline = false) => {
             let text = '';