@accelint/design-toolkit 9.9.2 → 9.11.0

package/dist/components/floating-card/context.d.ts

@@ -10,27 +10,34 @@
  * governing permissions and limitations under the License.
  */
 
-import * as react25 from "react";
-import { DockviewApi } from "dockview-react";
-import { UniqueId } from "@accelint/core/utility/uuid";
+import { FloatingCardContextValue } from "./types.js";
+import * as react13 from "react";
 
 //#region src/components/floating-card/context.d.ts
-type FloatingCardContextValue = {
-  cards: Record<UniqueId, HTMLDivElement>;
-  addRef: (id: UniqueId, ref: HTMLDivElement | null) => void;
-  removeRef: (view: UniqueId) => void;
-  closeCard: (id: UniqueId) => void;
-  api: DockviewApi | null;
-};
-declare const FloatingCardContext: react25.Context<FloatingCardContextValue | null>;
+declare const FloatingCardContext: react13.Context<FloatingCardContextValue | null>;
 /**
- * Hook to access the floating card context.
- * Must be used within a FloatingCardProvider.
+ * Hook to access floating card management functionality.
  *
+ * Provides access to card registry, ref management, and programmatic control
+ * over opening, closing, and pinning floating cards.
+ *
+ * @returns Context value with card management methods and state.
  * @throws {Error} If used outside of a FloatingCardProvider.
- * @returns The floating card context value.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { closeCard, togglePinCard } = useFloatingCard();
+ *
+ *   return (
+ *     <button onClick={() => closeCard('my-card-id' as UniqueId)}>
+ *       Close Card
+ *     </button>
+ *   );
+ * }
+ * ```
  */
 declare function useFloatingCard(): FloatingCardContextValue;
 //#endregion
-export { FloatingCardContext, FloatingCardContextValue, useFloatingCard };
+export { FloatingCardContext, useFloatingCard };
 //# sourceMappingURL=context.d.ts.map

package/dist/components/floating-card/context.js

@@ -16,11 +16,26 @@ import { createContext, useContext } from "react";
 //#region src/components/floating-card/context.tsx
 const FloatingCardContext = createContext(null);
 /**
-* Hook to access the floating card context.
-* Must be used within a FloatingCardProvider.
+* Hook to access floating card management functionality.
 *
+* Provides access to card registry, ref management, and programmatic control
+* over opening, closing, and pinning floating cards.
+*
+* @returns Context value with card management methods and state.
 * @throws {Error} If used outside of a FloatingCardProvider.
-* @returns The floating card context value.
+*
+* @example
+* ```tsx
+* function MyComponent() {
+*   const { closeCard, togglePinCard } = useFloatingCard();
+*
+*   return (
+*     <button onClick={() => closeCard('my-card-id' as UniqueId)}>
+*       Close Card
+*     </button>
+*   );
+* }
+* ```
 */
 function useFloatingCard() {
 	const context = useContext(FloatingCardContext);

package/dist/components/floating-card/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","names":[],"sources":["../../../src/components/floating-card/context.tsx"],"sourcesContent":["// __private-exports\n/*\n * Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nimport { createContext, useContext } from 'react';\nimport type { UniqueId } from '@accelint/core/utility/uuid';\nimport type { DockviewApi } from 'dockview-react';\n\nexport type FloatingCardContextValue = {\n  cards: Record<UniqueId, HTMLDivElement>;\n  addRef: (id: UniqueId, ref: HTMLDivElement | null) => void;\n  removeRef: (view: UniqueId) => void;\n  closeCard: (id: UniqueId) => void;\n  api: DockviewApi | null;\n};\n\nexport const FloatingCardContext =\n  createContext<FloatingCardContextValue | null>(null);\n/**\n * Hook to access the floating card context.\n * Must be used within a FloatingCardProvider.\n *\n * @throws {Error} If used outside of a FloatingCardProvider.\n * @returns The floating card context value.\n */\nexport function useFloatingCard(): FloatingCardContextValue {\n  const context = useContext(FloatingCardContext);\n  if (!context) {\n    throw new Error(\n      'useFloatingCard must be used within a FloatingCardProvider.',\n    );\n  }\n  return context;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAyBA,MAAa,sBACX,cAA+C,KAAK;;;;;;;;AAQtD,SAAgB,kBAA4C;CAC1D,MAAM,UAAU,WAAW,oBAAoB;AAC/C,KAAI,CAAC,QACH,OAAM,IAAI,MACR,8DACD;AAEH,QAAO"}
+{"version":3,"file":"context.js","names":[],"sources":["../../../src/components/floating-card/context.tsx"],"sourcesContent":["// __private-exports\n/*\n * Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nimport { createContext, useContext } from 'react';\nimport type { FloatingCardContextValue } from './types';\n\nexport const FloatingCardContext =\n  createContext<FloatingCardContextValue | null>(null);\n/**\n * Hook to access floating card management functionality.\n *\n * Provides access to card registry, ref management, and programmatic control\n * over opening, closing, and pinning floating cards.\n *\n * @returns Context value with card management methods and state.\n * @throws {Error} If used outside of a FloatingCardProvider.\n *\n * @example\n * ```tsx\n * function MyComponent() {\n *   const { closeCard, togglePinCard } = useFloatingCard();\n *\n *   return (\n *     <button onClick={() => closeCard('my-card-id' as UniqueId)}>\n *       Close Card\n *     </button>\n *   );\n * }\n * ```\n */\nexport function useFloatingCard(): FloatingCardContextValue {\n  const context = useContext(FloatingCardContext);\n  if (!context) {\n    throw new Error(\n      'useFloatingCard must be used within a FloatingCardProvider.',\n    );\n  }\n  return context;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAgBA,MAAa,sBACX,cAA+C,KAAK;;;;;;;;;;;;;;;;;;;;;;;AAuBtD,SAAgB,kBAA4C;CAC1D,MAAM,UAAU,WAAW,oBAAoB;AAC/C,KAAI,CAAC,QACH,OAAM,IAAI,MACR,8DACD;AAEH,QAAO"}

package/dist/components/floating-card/index.d.ts

@@ -10,33 +10,12 @@
  * governing permissions and limitations under the License.
  */
 
-import * as react18 from "react";
+import { FloatingCardProps } from "./types.js";
+import * as react14 from "react";
 import { PropsWithChildren } from "react";
-import { UniqueId } from "@accelint/core";
 
 //#region src/components/floating-card/index.d.ts
-type FloatingCardProps = Readonly<{
-  id: UniqueId;
-  title?: string;
-  /**
-   * Controls whether the floating card is rendered.
-   *
-   * When `true`, the card registers with the floating card engine and renders its
-   * children via a portal. When `false`, the card is closed and removed.
-   *
-   * @defaultValue true
-   */
-  isOpen?: boolean;
-  /**
-   * Initial dimensions of the floating card panel.
-   *
-   * @defaultValue { width: 300, height: 400 }
-   */
-  initialDimensions?: Readonly<{
-    width: number;
-    height: number;
-  }>;
-}>;
+
 /**
  * Renders its children into a floating card using React portals.
  *
@@ -47,19 +26,45 @@ type FloatingCardProps = Readonly<{
  * @param title - Optional title displayed in the floating card header.
  * @param isOpen - Whether the floating card is rendered. Defaults to `true`.
  * @param initialDimensions - Initial width and height of the floating card. Defaults to `{ width: 300, height: 400 }`.
+ * @param initialPosition - Initial x and y coordinates of the floating card.
  * @param children - React children to render inside the floating card.
+ * @returns The floating card component (portaled content) or null.
  *
  * @remarks
  * - Requires `FloatingCardProvider` as an ancestor.
  * - The floating card is only rendered if a valid DOM reference exists for the given `id`.
+ *
+ * @example
+ * ```tsx
+ * import { uuid } from '@accelint/core/utility/uuid';
+ *
+ * const cardId = uuid();
+ * const [isOpen, setIsOpen] = useState(true);
+ *
+ * <FloatingCardProvider>
+ *   <FloatingCard
+ *     id={cardId}
+ *     title="Settings Panel"
+ *     isOpen={isOpen}
+ *     initialDimensions={{ width: 400, height: 500 }}
+ *   >
+ *     <SettingsForm />
+ *   </FloatingCard>
+ *
+ *   <button onClick={() => setIsOpen(!isOpen)}>
+ *     Toggle Panel
+ *   </button>
+ * </FloatingCardProvider>
+ * ```
  */
 declare function FloatingCard({
   id,
   children,
   title,
   isOpen,
-  initialDimensions
-}: PropsWithChildren<FloatingCardProps>): react18.ReactPortal | null;
+  initialDimensions,
+  initialPosition
+}: PropsWithChildren<FloatingCardProps>): react14.ReactPortal | null;
 //#endregion
-export { FloatingCard, FloatingCardProps };
+export { FloatingCard };
 //# sourceMappingURL=index.d.ts.map

package/dist/components/floating-card/index.js

@@ -30,29 +30,57 @@ const defaultDimensions = {
 * @param title - Optional title displayed in the floating card header.
 * @param isOpen - Whether the floating card is rendered. Defaults to `true`.
 * @param initialDimensions - Initial width and height of the floating card. Defaults to `{ width: 300, height: 400 }`.
+* @param initialPosition - Initial x and y coordinates of the floating card.
 * @param children - React children to render inside the floating card.
+* @returns The floating card component (portaled content) or null.
 *
 * @remarks
 * - Requires `FloatingCardProvider` as an ancestor.
 * - The floating card is only rendered if a valid DOM reference exists for the given `id`.
+*
+* @example
+* ```tsx
+* import { uuid } from '@accelint/core/utility/uuid';
+*
+* const cardId = uuid();
+* const [isOpen, setIsOpen] = useState(true);
+*
+* <FloatingCardProvider>
+*   <FloatingCard
+*     id={cardId}
+*     title="Settings Panel"
+*     isOpen={isOpen}
+*     initialDimensions={{ width: 400, height: 500 }}
+*   >
+*     <SettingsForm />
+*   </FloatingCard>
+*
+*   <button onClick={() => setIsOpen(!isOpen)}>
+*     Toggle Panel
+*   </button>
+* </FloatingCardProvider>
+* ```
 */
-function FloatingCard({ id, children, title, isOpen = true, initialDimensions }) {
-	const floatingCardContext = useFloatingCard();
+function FloatingCard({ id, children, title, isOpen = true, initialDimensions, initialPosition }) {
+	const { cards, api: floatingCardApi } = useFloatingCard();
 	const { width, height } = initialDimensions ?? defaultDimensions;
+	const { x, y } = initialPosition ?? {};
 	useEffect(() => {
-		if (!floatingCardContext.api) return;
+		if (!floatingCardApi) return;
 		if (!isOpen) {
-			floatingCardContext.api.getPanel(id)?.api.close();
+			floatingCardApi.getPanel(id)?.api.close();
 			return;
 		}
-		if (!floatingCardContext.api.getPanel(id)) {
-			const panel = floatingCardContext.api.addPanel({
+		if (!floatingCardApi.getPanel(id)) {
+			const panel = floatingCardApi.addPanel({
 				id,
 				title,
 				component: "default",
 				floating: {
 					width,
-					height
+					height,
+					x,
+					y
 				}
 			});
 			panel.group.locked = "no-drop-target";
@@ -63,17 +91,19 @@ function FloatingCard({ id, children, title, isOpen = true, initialDimensions })
 		isOpen,
 		width,
 		height,
-		floatingCardContext.api
+		x,
+		y,
+		floatingCardApi
 	]);
 	useEffect(() => {
-		const panel = floatingCardContext.api?.getPanel(id);
+		const panel = floatingCardApi?.getPanel(id);
 		if (panel) panel.setTitle(title ?? id);
 	}, [
 		title,
-		floatingCardContext.api,
+		floatingCardApi,
 		id
 	]);
-	return isOpen && floatingCardContext.cards[id] ? createPortal(children, floatingCardContext.cards[id]) : null;
+	return isOpen && cards[id] ? createPortal(children, cards[id]) : null;
 }
 
 //#endregion

package/dist/components/floating-card/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../src/components/floating-card/index.tsx"],"sourcesContent":["/*\n * Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nimport { type PropsWithChildren, useEffect } from 'react';\nimport { createPortal } from 'react-dom';\nimport { useFloatingCard } from './context';\nimport type { UniqueId } from '@accelint/core';\n\nconst defaultDimensions = { width: 300, height: 400 } as const;\n\nexport type FloatingCardProps = Readonly<{\n  id: UniqueId;\n  title?: string;\n  /**\n   * Controls whether the floating card is rendered.\n   *\n   * When `true`, the card registers with the floating card engine and renders its\n   * children via a portal. When `false`, the card is closed and removed.\n   *\n   * @defaultValue true\n   */\n  isOpen?: boolean;\n  /**\n   * Initial dimensions of the floating card panel.\n   *\n   * @defaultValue { width: 300, height: 400 }\n   */\n  initialDimensions?: Readonly<{ width: number; height: number }>;\n}>;\n\n/**\n * Renders its children into a floating card using React portals.\n *\n * The `FloatingCard` component registers itself with the floating card engine on mount\n * and renders its children into the corresponding DOM node via a portal.\n *\n * @param id - Unique identifier for the floating card.\n * @param title - Optional title displayed in the floating card header.\n * @param isOpen - Whether the floating card is rendered. Defaults to `true`.\n * @param initialDimensions - Initial width and height of the floating card. Defaults to `{ width: 300, height: 400 }`.\n * @param children - React children to render inside the floating card.\n *\n * @remarks\n * - Requires `FloatingCardProvider` as an ancestor.\n * - The floating card is only rendered if a valid DOM reference exists for the given `id`.\n */\nexport function FloatingCard({\n  id,\n  children,\n  title,\n  isOpen = true,\n  initialDimensions,\n}: PropsWithChildren<FloatingCardProps>) {\n  const floatingCardContext = useFloatingCard();\n\n  const { width, height } = initialDimensions ?? defaultDimensions;\n\n  useEffect(() => {\n    // If the API is not available, we cannot register the card. This can happen if Dockview is not fully initialized yet.\n    if (!floatingCardContext.api) {\n      return;\n    }\n    if (!isOpen) {\n      floatingCardContext.api.getPanel(id)?.api.close();\n      return;\n    }\n\n    if (!floatingCardContext.api.getPanel(id)) {\n      const panel = floatingCardContext.api.addPanel({\n        id,\n        title,\n        component: 'default',\n        floating: { width, height },\n      });\n\n      panel.group.locked = 'no-drop-target';\n    }\n\n    // Cleanup not included here. Cleanup is done at the provider level when the card is removed from the `cards` registry.\n  }, [id, title, isOpen, width, height, floatingCardContext.api]);\n\n  useEffect(() => {\n    const panel = floatingCardContext.api?.getPanel(id);\n    if (panel) {\n      panel.setTitle(title ?? id);\n    }\n  }, [title, floatingCardContext.api, id]);\n\n  return isOpen && floatingCardContext.cards[id]\n    ? createPortal(children, floatingCardContext.cards[id])\n    : null;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAiBA,MAAM,oBAAoB;CAAE,OAAO;CAAK,QAAQ;CAAK;;;;;;;;;;;;;;;;;AAsCrD,SAAgB,aAAa,EAC3B,IACA,UACA,OACA,SAAS,MACT,qBACuC;CACvC,MAAM,sBAAsB,iBAAiB;CAE7C,MAAM,EAAE,OAAO,WAAW,qBAAqB;AAE/C,iBAAgB;AAEd,MAAI,CAAC,oBAAoB,IACvB;AAEF,MAAI,CAAC,QAAQ;AACX,uBAAoB,IAAI,SAAS,GAAG,EAAE,IAAI,OAAO;AACjD;;AAGF,MAAI,CAAC,oBAAoB,IAAI,SAAS,GAAG,EAAE;GACzC,MAAM,QAAQ,oBAAoB,IAAI,SAAS;IAC7C;IACA;IACA,WAAW;IACX,UAAU;KAAE;KAAO;KAAQ;IAC5B,CAAC;AAEF,SAAM,MAAM,SAAS;;IAItB;EAAC;EAAI;EAAO;EAAQ;EAAO;EAAQ,oBAAoB;EAAI,CAAC;AAE/D,iBAAgB;EACd,MAAM,QAAQ,oBAAoB,KAAK,SAAS,GAAG;AACnD,MAAI,MACF,OAAM,SAAS,SAAS,GAAG;IAE5B;EAAC;EAAO,oBAAoB;EAAK;EAAG,CAAC;AAExC,QAAO,UAAU,oBAAoB,MAAM,MACvC,aAAa,UAAU,oBAAoB,MAAM,IAAI,GACrD"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/components/floating-card/index.tsx"],"sourcesContent":["/*\n * Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nimport { type PropsWithChildren, useEffect } from 'react';\nimport { createPortal } from 'react-dom';\nimport { useFloatingCard } from './context';\nimport type { FloatingCardProps } from './types';\n\nconst defaultDimensions = { width: 300, height: 400 } as const;\n\n/**\n * Renders its children into a floating card using React portals.\n *\n * The `FloatingCard` component registers itself with the floating card engine on mount\n * and renders its children into the corresponding DOM node via a portal.\n *\n * @param id - Unique identifier for the floating card.\n * @param title - Optional title displayed in the floating card header.\n * @param isOpen - Whether the floating card is rendered. Defaults to `true`.\n * @param initialDimensions - Initial width and height of the floating card. Defaults to `{ width: 300, height: 400 }`.\n * @param initialPosition - Initial x and y coordinates of the floating card.\n * @param children - React children to render inside the floating card.\n * @returns The floating card component (portaled content) or null.\n *\n * @remarks\n * - Requires `FloatingCardProvider` as an ancestor.\n * - The floating card is only rendered if a valid DOM reference exists for the given `id`.\n *\n * @example\n * ```tsx\n * import { uuid } from '@accelint/core/utility/uuid';\n *\n * const cardId = uuid();\n * const [isOpen, setIsOpen] = useState(true);\n *\n * <FloatingCardProvider>\n *   <FloatingCard\n *     id={cardId}\n *     title=\"Settings Panel\"\n *     isOpen={isOpen}\n *     initialDimensions={{ width: 400, height: 500 }}\n *   >\n *     <SettingsForm />\n *   </FloatingCard>\n *\n *   <button onClick={() => setIsOpen(!isOpen)}>\n *     Toggle Panel\n *   </button>\n * </FloatingCardProvider>\n * ```\n */\nexport function FloatingCard({\n  id,\n  children,\n  title,\n  isOpen = true,\n  initialDimensions,\n  initialPosition,\n}: PropsWithChildren<FloatingCardProps>) {\n  const { cards, api: floatingCardApi } = useFloatingCard();\n\n  const { width, height } = initialDimensions ?? defaultDimensions;\n  const { x, y } = initialPosition ?? {};\n\n  // Register card with Dockview API when isOpen changes.\n  // Early return if API not ready (Dockview not fully initialized).\n  useEffect(() => {\n    if (!floatingCardApi) {\n      return;\n    }\n    if (!isOpen) {\n      floatingCardApi.getPanel(id)?.api.close();\n      return;\n    }\n\n    if (!floatingCardApi.getPanel(id)) {\n      const panel = floatingCardApi.addPanel({\n        id,\n        title,\n        component: 'default',\n        floating: { width, height, x, y },\n      });\n\n      panel.group.locked = 'no-drop-target';\n    }\n\n    // Cleanup not included here. Cleanup is done at the provider level when the card is removed from the `cards` registry.\n  }, [id, title, isOpen, width, height, x, y, floatingCardApi]);\n\n  useEffect(() => {\n    const panel = floatingCardApi?.getPanel(id);\n    if (panel) {\n      panel.setTitle(title ?? id);\n    }\n  }, [title, floatingCardApi, id]);\n\n  return isOpen && cards[id] ? createPortal(children, cards[id]) : null;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAiBA,MAAM,oBAAoB;CAAE,OAAO;CAAK,QAAQ;CAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CrD,SAAgB,aAAa,EAC3B,IACA,UACA,OACA,SAAS,MACT,mBACA,mBACuC;CACvC,MAAM,EAAE,OAAO,KAAK,oBAAoB,iBAAiB;CAEzD,MAAM,EAAE,OAAO,WAAW,qBAAqB;CAC/C,MAAM,EAAE,GAAG,MAAM,mBAAmB,EAAE;AAItC,iBAAgB;AACd,MAAI,CAAC,gBACH;AAEF,MAAI,CAAC,QAAQ;AACX,mBAAgB,SAAS,GAAG,EAAE,IAAI,OAAO;AACzC;;AAGF,MAAI,CAAC,gBAAgB,SAAS,GAAG,EAAE;GACjC,MAAM,QAAQ,gBAAgB,SAAS;IACrC;IACA;IACA,WAAW;IACX,UAAU;KAAE;KAAO;KAAQ;KAAG;KAAG;IAClC,CAAC;AAEF,SAAM,MAAM,SAAS;;IAItB;EAAC;EAAI;EAAO;EAAQ;EAAO;EAAQ;EAAG;EAAG;EAAgB,CAAC;AAE7D,iBAAgB;EACd,MAAM,QAAQ,iBAAiB,SAAS,GAAG;AAC3C,MAAI,MACF,OAAM,SAAS,SAAS,GAAG;IAE5B;EAAC;EAAO;EAAiB;EAAG,CAAC;AAEhC,QAAO,UAAU,MAAM,MAAM,aAAa,UAAU,MAAM,IAAI,GAAG"}

package/dist/components/floating-card/provider.d.ts

@@ -10,55 +10,53 @@
  * governing permissions and limitations under the License.
  */
 
-import { PropsWithChildren, ReactNode } from "react";
-import * as react_jsx_runtime69 from "react/jsx-runtime";
+import { FloatingCardProviderProps } from "./types.js";
+import * as react_jsx_runtime50 from "react/jsx-runtime";
 
 //#region src/components/floating-card/provider.d.ts
-/** A value that is either `T` directly, or a function that receives the active card id and returns `T`. */
-type MaybeFactory<T> = T | ((cardId: string) => T);
-type FloatingCardProviderProps = Readonly<PropsWithChildren<{
-  /**
-   * Optional icon rendered at the very start of the floating card header.
-   * Can be a `ReactNode` or a function `(cardId: string) => ReactNode`.
-   */
-  icon?: MaybeFactory<ReactNode>;
-  /**
-   * Optional action buttons rendered in the floating card header before the close button.
-   * Can include dividers to separate groups of actions.
-   * Can be an array or a function `(cardId: string) => array` to return
-   * per-floating card actions.
-   */
-  headerActions?: MaybeFactory<({
-    icon: ReactNode;
-    onClick: () => void;
-  } | 'divider')[]>;
-  className?: string;
-}>>;
+
 /**
  * Provides a context and layout area for floating cards within the application.
  *
- * Wraps its children with floating card context and renders a floating card engine instance
- * to manage docking and layout.
+ * Wraps children with floating card context and renders a Dockview instance to manage
+ * docking, dragging, and layout of floating cards.
  *
  * @param props - The props for the FloatingCardProvider component.
  * @param props.children - Child components rendered inside the floating card provider.
- * @param props.icon - Optional icon.
- * @param props.headerActions - Optional actions for the header.
+ * @param props.icon - Optional icon rendered in all card headers (static or factory).
+ * @param props.headerActions - Optional action buttons for card headers (static or factory).
  * @param props.className - Additional CSS class names for styling.
- *
  * @returns The FloatingCardProvider component that manages floating card layout and context.
  *
  * @remarks
- * - Manages registration and unregistration of floating card references.
- * - Exposes `closeCard` via context for child components.
- * - Ensures floating cards are bounded within the viewport.
+ * - Manages registration and cleanup of floating card DOM references
+ * - Exposes closeCard, togglePinCard, and isPinned via context
+ * - Automatically cleans up refs when cards are removed via any path (drag close, group close, API close)
+ * - Cards are bounded within the viewport
+ *
+ * @example
+ * ```tsx
+ * <FloatingCardProvider
+ *   icon={<AppLogo />}
+ *   headerActions={[
+ *     { icon: <SettingsIcon />, onClick: openSettings },
+ *     'divider',
+ *     'pin'
+ *   ]}
+ * >
+ *   <FloatingCard id="panel-1" title="My Panel">
+ *     <div>Panel content</div>
+ *   </FloatingCard>
+ * </FloatingCardProvider>
+ * ```
  */
 declare function FloatingCardProvider({
   children,
   icon,
   headerActions,
+  initialPinned,
   className
-}: FloatingCardProviderProps): react_jsx_runtime69.JSX.Element;
+}: FloatingCardProviderProps): react_jsx_runtime50.JSX.Element;
 //#endregion
-export { FloatingCardProvider, FloatingCardProviderProps };
+export { FloatingCardProvider };
 //# sourceMappingURL=provider.d.ts.map

package/dist/components/floating-card/provider.js

@@ -15,30 +15,46 @@ import { Icon } from "../icon/index.js";
 import { Button } from "../button/index.js";
 import { Divider } from "../divider/index.js";
 import { FloatingCardContext, useFloatingCard } from "./context.js";
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { createHeaderAdapter } from "./utils.js";
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { clsx } from "@accelint/design-foundation/lib/utils";
 import { jsx, jsxs } from "react/jsx-runtime";
 import Cancel from "@accelint/icons/cancel";
+import PinIcon from "@accelint/icons/pin";
 import { DockviewReact } from "dockview-react";
 import styles from "./styles.module.css";
 
 //#region src/components/floating-card/provider.tsx
 /**
 * Internal component that registers a DOM ref for a card container.
-* Used by the floating card engine to mount portal targets.
+*
+* Used by the floating card engine to mount portal targets. Also manages
+* the data-pinned attribute on the resize container to control drag handle visibility.
+*
+* @param props - Dockview panel props containing the card ID.
 */
 function FloatingCardContainer(props) {
-	const { addRef } = useFloatingCard();
+	const { addRef, isPinned, subscribeToPinState } = useFloatingCard();
+	const cardId = props.api.id;
+	const pinned = useSyncExternalStore(subscribeToPinState, () => isPinned(cardId), () => false);
+	const cardRef = useRef(null);
 	const refCallback = useCallback((ref) => {
-		addRef(props.api.id, ref);
-	}, [addRef, props.api.id]);
+		cardRef.current = ref;
+		addRef(cardId, ref);
+	}, [addRef, cardId]);
+	useEffect(() => {
+		const container = cardRef.current?.closest(".dv-resize-container");
+		if (!container) return;
+		if (pinned) container.dataset.pinned = "";
+		else delete container.dataset.pinned;
+	}, [pinned]);
 	return /* @__PURE__ */ jsx("div", {
 		className: styles.cardContent,
 		ref: refCallback
 	});
 }
 /**
-* Default left header showing an optional custom icon (or a placeholder) and the card's title.
+* Default left header showing an optional custom icon and the card's title.
 */
 function DefaultLeftHeader({ title, icon, id }) {
 	return /* @__PURE__ */ jsxs("div", {
@@ -47,19 +63,39 @@ function DefaultLeftHeader({ title, icon, id }) {
 			size: "small",
 			children: icon
 		}) : null, title && title !== id ? /* @__PURE__ */ jsx("div", {
-			className: styles.headerTitle,
-			children: title
+			className: styles.headerTitleContainer,
+			children: /* @__PURE__ */ jsx("div", {
+				className: styles.headerTitle,
+				children: title
+			})
 		}) : null]
 	});
 }
+/** Stable no-op subscribe for useSyncExternalStore when no pin subscription is available. */
+const noopSubscribe = () => () => void 0;
 /**
 * Default right header showing optional action buttons and an always-present close button.
+*
+* @remarks Handles rendering of 'divider' and 'pin' action types specially.
 */
-function DefaultRightHeader({ closeGroup, headerActions, id }) {
+function DefaultRightHeader({ closeGroup, headerActions, id, togglePinCard, isPinned, subscribeToPinState }) {
+	const pinned = useSyncExternalStore(subscribeToPinState ?? noopSubscribe, () => id && isPinned ? isPinned(id) : false, () => false);
 	return /* @__PURE__ */ jsxs("div", {
 		className: styles.headerSide,
 		children: [headerActions?.map((action, index) => {
 			if (action === "divider") return /* @__PURE__ */ jsx(Divider, { orientation: "vertical" }, `${id}-divider-${index}`);
+			if (action === "pin") return /* @__PURE__ */ jsx(Button, {
+				className: styles.pinButton,
+				variant: "icon",
+				size: "small",
+				color: pinned ? "accent" : void 0,
+				"aria-label": "Pin",
+				"aria-pressed": pinned,
+				onClick: () => {
+					if (id && togglePinCard) togglePinCard(id);
+				},
+				children: /* @__PURE__ */ jsx(Icon, { children: /* @__PURE__ */ jsx(PinIcon, {}) })
+			}, `${id}-pin-${index}`);
 			return /* @__PURE__ */ jsx(Button, {
 				variant: "icon",
 				size: "small",
@@ -74,67 +110,76 @@ function DefaultRightHeader({ closeGroup, headerActions, id }) {
 		})]
 	});
 }
-/**
-* Creates an adapter component to map Dockview's header action props to our custom header component props.
-*/
-function createHeaderAdapter(Component, options) {
-	function HeaderAdapter(props) {
-		const panelId = props.panels[0]?.id ?? "";
-		const [title, setTitle] = useState(props.activePanel?.title);
-		useEffect(() => {
-			const panel = props.activePanel;
-			if (!panel) return;
-			setTitle(panel.title);
-			const disposable = panel.api.onDidTitleChange(() => {
-				setTitle(panel.title);
-			});
-			return () => {
-				disposable.dispose();
-			};
-		}, [props.activePanel]);
-		return /* @__PURE__ */ jsx(Component, {
-			icon: props.activePanel ? typeof options?.icon === "function" ? options.icon(panelId) : options?.icon : void 0,
-			headerActions: typeof options?.headerActions === "function" ? options.headerActions(panelId) : options?.headerActions,
-			title,
-			id: props.activePanel?.id,
-			closeGroup: () => props.api.close()
-		});
-	}
-	HeaderAdapter.displayName = `HeaderAdapter(${Component.displayName ?? Component.name ?? "Anonymous"})`;
-	return HeaderAdapter;
-}
 const components = { default: FloatingCardContainer };
 /**
 * Provides a context and layout area for floating cards within the application.
 *
-* Wraps its children with floating card context and renders a floating card engine instance
-* to manage docking and layout.
+* Wraps children with floating card context and renders a Dockview instance to manage
+* docking, dragging, and layout of floating cards.
 *
 * @param props - The props for the FloatingCardProvider component.
 * @param props.children - Child components rendered inside the floating card provider.
-* @param props.icon - Optional icon.
-* @param props.headerActions - Optional actions for the header.
+* @param props.icon - Optional icon rendered in all card headers (static or factory).
+* @param props.headerActions - Optional action buttons for card headers (static or factory).
 * @param props.className - Additional CSS class names for styling.
-*
 * @returns The FloatingCardProvider component that manages floating card layout and context.
 *
 * @remarks
-* - Manages registration and unregistration of floating card references.
-* - Exposes `closeCard` via context for child components.
-* - Ensures floating cards are bounded within the viewport.
+* - Manages registration and cleanup of floating card DOM references
+* - Exposes closeCard, togglePinCard, and isPinned via context
+* - Automatically cleans up refs when cards are removed via any path (drag close, group close, API close)
+* - Cards are bounded within the viewport
+*
+* @example
+* ```tsx
+* <FloatingCardProvider
+*   icon={<AppLogo />}
+*   headerActions={[
+*     { icon: <SettingsIcon />, onClick: openSettings },
+*     'divider',
+*     'pin'
+*   ]}
+* >
+*   <FloatingCard id="panel-1" title="My Panel">
+*     <div>Panel content</div>
+*   </FloatingCard>
+* </FloatingCardProvider>
+* ```
 */
-function FloatingCardProvider({ children, icon, headerActions, className }) {
+function FloatingCardProvider({ children, icon, headerActions, initialPinned, className }) {
 	const [api, setApi] = useState(null);
 	const [cards, setCards] = useState({});
+	const pinnedCardsRef = useRef(new Set(initialPinned));
+	const pinListenersRef = useRef(/* @__PURE__ */ new Set());
 	const closeCard = useCallback((id) => {
 		api?.getPanel(id)?.api.close();
 	}, [api]);
+	const togglePinCard = useCallback((id) => {
+		const next = new Set(pinnedCardsRef.current);
+		if (next.has(id)) next.delete(id);
+		else next.add(id);
+		pinnedCardsRef.current = next;
+		for (const listener of pinListenersRef.current) listener();
+	}, []);
+	const isPinned = useCallback((id) => pinnedCardsRef.current.has(id), []);
+	const subscribeToPinState = useCallback((callback) => {
+		pinListenersRef.current.add(callback);
+		return () => {
+			pinListenersRef.current.delete(callback);
+		};
+	}, []);
 	const removeRef = useCallback((view) => {
 		setCards((prev) => {
 			const newCards = { ...prev };
 			delete newCards[view];
 			return newCards;
 		});
+		if (pinnedCardsRef.current.has(view)) {
+			const next = new Set(pinnedCardsRef.current);
+			next.delete(view);
+			pinnedCardsRef.current = next;
+			for (const listener of pinListenersRef.current) listener();
+		}
 	}, []);
 	const addRef = useCallback((id, ref) => {
 		if (ref) setCards((prev) => {
@@ -159,16 +204,32 @@ function FloatingCardProvider({ children, icon, headerActions, className }) {
 		addRef,
 		removeRef,
 		closeCard,
+		togglePinCard,
+		isPinned,
+		subscribeToPinState,
 		api
 	}), [
 		cards,
 		closeCard,
 		removeRef,
 		api,
-		addRef
+		addRef,
+		togglePinCard,
+		isPinned,
+		subscribeToPinState
 	]);
 	const leftAdapter = useMemo(() => createHeaderAdapter(DefaultLeftHeader, { icon }), [icon]);
-	const rightAdapter = useMemo(() => createHeaderAdapter(DefaultRightHeader, { headerActions }), [headerActions]);
+	const rightAdapter = useMemo(() => createHeaderAdapter(DefaultRightHeader, {
+		headerActions,
+		togglePinCard,
+		isPinned,
+		subscribeToPinState
+	}), [
+		headerActions,
+		togglePinCard,
+		isPinned,
+		subscribeToPinState
+	]);
 	const theme = useMemo(() => ({
 		name: "accelint",
 		className: styles.floatingCardProvider ?? ""