@accelint/design-toolkit 9.9.2 → 9.10.0

package/dist/components/drawer/styles.module.css

@@ -61,8 +61,18 @@
   .drawer {
     @apply bg-surface-default text-body-m pointer-events-none relative flex flex-col;
 
+    @variant motion-safe {
+      transition: transform var(--animation-duration-slow)
+        var(--animation-easing-standard);
+    }
+
     @variant placement-top {
       @apply col-span-full row-start-1 row-end-2;
+      transform: translateY(-100%);
+
+      @variant open {
+        transform: translateY(0);
+      }
 
       @variant group-extend-right/layout {
         @apply col-end-3;
@@ -79,6 +89,11 @@
 
     @variant placement-right {
       @apply col-start-3 col-end-4 row-span-full;
+      transform: translateX(100%);
+
+      @variant open {
+        transform: translateX(0);
+      }
 
       @variant group-extend-top/layout {
         @apply row-start-2;
@@ -95,6 +110,11 @@
 
     @variant placement-bottom {
       @apply col-span-full row-start-3 row-end-4;
+      transform: translateY(100%);
+
+      @variant open {
+        transform: translateY(0);
+      }
 
       @variant group-extend-right/layout {
         @apply col-end-3;
@@ -111,6 +131,11 @@
 
     @variant placement-left {
       @apply col-start-1 col-end-2 row-span-full;
+      transform: translateX(-100%);
+
+      @variant open {
+        transform: translateX(0);
+      }
 
       @variant group-extend-top/layout {
         @apply row-start-2;
@@ -205,10 +230,37 @@
   }
 
   .panel {
-    @apply gap-s p-l hidden h-full min-h-0 flex-col;
+    @apply gap-s p-l flex h-full min-h-0 flex-col;
+    opacity: 0;
+    pointer-events: none;
+
+    @variant motion-safe {
+      transition:
+        transform var(--animation-duration-fast)
+          var(--animation-easing-standard),
+        opacity var(--animation-duration-fast) var(--animation-easing-standard);
+    }
+
+    @variant group-placement-left/drawer {
+      transform: translateX(-100%);
+    }
+
+    @variant group-placement-right/drawer {
+      transform: translateX(100%);
+    }
+
+    @variant group-placement-top/drawer {
+      transform: translateY(-100%);
+    }
+
+    @variant group-placement-bottom/drawer {
+      transform: translateY(100%);
+    }
 
     @variant group-open/drawer {
-      @apply flex;
+      opacity: 1;
+      pointer-events: auto;
+      transform: translate(0, 0);
     }
 
     @variant group-placement-left/drawer {

package/dist/components/drawer/trigger.d.ts

@@ -12,7 +12,7 @@
 
 import { DrawerTriggerProps } from "./types.js";
 import "client-only";
-import * as react_jsx_runtime62 from "react/jsx-runtime";
+import * as react_jsx_runtime75 from "react/jsx-runtime";
 
 //#region src/components/drawer/trigger.d.ts
 
@@ -47,7 +47,7 @@ import * as react_jsx_runtime62 from "react/jsx-runtime";
 declare function DrawerTrigger({
   for: events,
   ...rest
-}: DrawerTriggerProps): react_jsx_runtime62.JSX.Element;
+}: DrawerTriggerProps): react_jsx_runtime75.JSX.Element;
 //#endregion
 export { DrawerTrigger };
 //# sourceMappingURL=trigger.d.ts.map

package/dist/components/drawer/view.d.ts

@@ -13,7 +13,7 @@
 import { ViewStackViewProps } from "../view-stack/types.js";
 import "client-only";
 import { ComponentPropsWithRef } from "react";
-import * as react_jsx_runtime67 from "react/jsx-runtime";
+import * as react_jsx_runtime55 from "react/jsx-runtime";
 
 //#region src/components/drawer/view.d.ts
 
@@ -44,7 +44,7 @@ declare function DrawerView({
   children,
   className,
   ...rest
-}: ViewStackViewProps & ComponentPropsWithRef<'div'>): react_jsx_runtime67.JSX.Element;
+}: ViewStackViewProps & ComponentPropsWithRef<'div'>): react_jsx_runtime55.JSX.Element;
 //#endregion
 export { DrawerView };
 //# sourceMappingURL=view.d.ts.map

package/dist/components/flashcard/index.d.ts

@@ -12,14 +12,14 @@
 
 import { FlashcardComponentProps, FlashcardDetailsListProps, FlashcardProps } from "./types.js";
 import "client-only";
-import * as react24 from "react";
-import * as react_jsx_runtime71 from "react/jsx-runtime";
+import * as react19 from "react";
+import * as react_jsx_runtime57 from "react/jsx-runtime";
 
 //#region src/components/flashcard/index.d.ts
 /**
  * Context for sharing Flashcard state across child components.
  */
-declare const FlashcardContext: react24.Context<FlashcardProps>;
+declare const FlashcardContext: react19.Context<FlashcardProps>;
 /**
  * Flashcard - A quick visual identifier for map entity data.
  *
@@ -46,7 +46,7 @@ declare const FlashcardContext: react24.Context<FlashcardProps>;
  * </Flashcard>
  * ```
  */
-declare function Flashcard(props: FlashcardProps): react_jsx_runtime71.JSX.Element;
+declare function Flashcard(props: FlashcardProps): react_jsx_runtime57.JSX.Element;
 declare namespace Flashcard {
   var displayName: string;
 }
@@ -68,7 +68,7 @@ declare namespace Flashcard {
  * </Flashcard>
  * ```
  */
-declare function FlashcardHero(props: FlashcardComponentProps): react_jsx_runtime71.JSX.Element;
+declare function FlashcardHero(props: FlashcardComponentProps): react_jsx_runtime57.JSX.Element;
 declare namespace FlashcardHero {
   var displayName: string;
 }
@@ -92,7 +92,7 @@ declare namespace FlashcardHero {
  * </Flashcard>
  * ```
  */
-declare function FlashcardAdditionalData(props: FlashcardComponentProps): react_jsx_runtime71.JSX.Element | null;
+declare function FlashcardAdditionalData(props: FlashcardComponentProps): react_jsx_runtime57.JSX.Element | null;
 declare namespace FlashcardAdditionalData {
   var displayName: string;
 }
@@ -119,7 +119,7 @@ declare namespace FlashcardAdditionalData {
  * </Flashcard>
  * ```
  */
-declare function FlashcardDetailsList(props: FlashcardDetailsListProps): react_jsx_runtime71.JSX.Element;
+declare function FlashcardDetailsList(props: FlashcardDetailsListProps): react_jsx_runtime57.JSX.Element;
 declare namespace FlashcardDetailsList {
   var displayName: string;
 }
@@ -141,7 +141,7 @@ declare namespace FlashcardDetailsList {
  * </FlashcardDetailsList>
  * ```
  */
-declare function FlashcardDetailsLabel(props: FlashcardComponentProps): react_jsx_runtime71.JSX.Element;
+declare function FlashcardDetailsLabel(props: FlashcardComponentProps): react_jsx_runtime57.JSX.Element;
 declare namespace FlashcardDetailsLabel {
   var displayName: string;
 }
@@ -163,7 +163,7 @@ declare namespace FlashcardDetailsLabel {
  * </FlashcardDetailsList>
  * ```
  */
-declare function FlashcardDetailsValue(props: FlashcardComponentProps): react_jsx_runtime71.JSX.Element;
+declare function FlashcardDetailsValue(props: FlashcardComponentProps): react_jsx_runtime57.JSX.Element;
 declare namespace FlashcardDetailsValue {
   var displayName: string;
 }

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

@@ -10,25 +10,57 @@
  * governing permissions and limitations under the License.
  */
 
-import * as react25 from "react";
+import * as react15 from "react";
 import { DockviewApi } from "dockview-react";
 import { UniqueId } from "@accelint/core/utility/uuid";
 
 //#region src/components/floating-card/context.d.ts
+/**
+ * Context value providing floating card management functionality.
+ *
+ * @remarks
+ * Exposed via FloatingCardProvider to child components. Use useFloatingCard() hook to access.
+ */
 type FloatingCardContextValue = {
+  /** Registry mapping card IDs to their rendered DOM containers */
   cards: Record<UniqueId, HTMLDivElement>;
+  /** Registers a DOM ref for a card container after it mounts */
   addRef: (id: UniqueId, ref: HTMLDivElement | null) => void;
+  /** Unregisters a card's DOM ref when it's removed */
   removeRef: (view: UniqueId) => void;
+  /** Programmatically closes a floating card by ID */
   closeCard: (id: UniqueId) => void;
+  /** Toggles pin state for a floating card, disabling drag when pinned */
+  togglePinCard: (id: UniqueId) => void;
+  /** Checks if a floating card is currently pinned */
+  isPinned: (id: UniqueId) => boolean;
+  /** Subscribes to pin state changes; returns an unsubscribe function */
+  subscribeToPinState: (callback: () => void) => () => void;
+  /** Dockview API instance, null until FloatingCardProvider's onReady fires */
   api: DockviewApi | null;
 };
-declare const FloatingCardContext: react25.Context<FloatingCardContextValue | null>;
+declare const FloatingCardContext: react15.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

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 { UniqueId } from '@accelint/core/utility/uuid';\nimport type { DockviewApi } from 'dockview-react';\n\n/**\n * Context value providing floating card management functionality.\n *\n * @remarks\n * Exposed via FloatingCardProvider to child components. Use useFloatingCard() hook to access.\n */\nexport type FloatingCardContextValue = {\n  /** Registry mapping card IDs to their rendered DOM containers */\n  cards: Record<UniqueId, HTMLDivElement>;\n\n  /** Registers a DOM ref for a card container after it mounts */\n  addRef: (id: UniqueId, ref: HTMLDivElement | null) => void;\n\n  /** Unregisters a card's DOM ref when it's removed */\n  removeRef: (view: UniqueId) => void;\n\n  /** Programmatically closes a floating card by ID */\n  closeCard: (id: UniqueId) => void;\n\n  /** Toggles pin state for a floating card, disabling drag when pinned */\n  togglePinCard: (id: UniqueId) => void;\n\n  /** Checks if a floating card is currently pinned */\n  isPinned: (id: UniqueId) => boolean;\n\n  /** Subscribes to pin state changes; returns an unsubscribe function */\n  subscribeToPinState: (callback: () => void) => () => void;\n\n  /** Dockview API instance, null until FloatingCardProvider's onReady fires */\n  api: DockviewApi | null;\n};\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":";;;;;;;;;;;;;;;;AAiDA,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

@@ -15,8 +15,23 @@ import { PropsWithChildren } from "react";
 import { UniqueId } from "@accelint/core";
 
 //#region src/components/floating-card/index.d.ts
+/**
+ * Props for the FloatingCard component.
+ *
+ * @example
+ * ```tsx
+ * const props: FloatingCardProps = {
+ *   id: 'panel-123' as UniqueId,
+ *   title: 'My Panel',
+ *   isOpen: true,
+ *   initialDimensions: { width: 350, height: 450 }
+ * };
+ * ```
+ */
 type FloatingCardProps = Readonly<{
+  /** Unique identifier for the floating card */
   id: UniqueId;
+  /** Optional title displayed in the floating card header */
   title?: string;
   /**
    * Controls whether the floating card is rendered.
@@ -36,6 +51,15 @@ type FloatingCardProps = Readonly<{
     width: number;
     height: number;
   }>;
+  /**
+   * Initial position of the floating card panel.
+   *
+   * When provided, sets the x and y coordinates of the floating card.
+   */
+  initialPosition?: Readonly<{
+    x: number;
+    y: number;
+  }>;
 }>;
 /**
  * Renders its children into a floating card using React portals.
@@ -47,18 +71,44 @@ 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
+  initialDimensions,
+  initialPosition
 }: PropsWithChildren<FloatingCardProps>): react18.ReactPortal | null;
 //#endregion
 export { FloatingCard, FloatingCardProps };

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 { UniqueId } from '@accelint/core';\n\nconst defaultDimensions = { width: 300, height: 400 } as const;\n\n/**\n * Props for the FloatingCard component.\n *\n * @example\n * ```tsx\n * const props: FloatingCardProps = {\n *   id: 'panel-123' as UniqueId,\n *   title: 'My Panel',\n *   isOpen: true,\n *   initialDimensions: { width: 350, height: 450 }\n * };\n * ```\n */\nexport type FloatingCardProps = Readonly<{\n  /** Unique identifier for the floating card */\n  id: UniqueId;\n  /** Optional title displayed in the floating card header */\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   * Initial position of the floating card panel.\n   *\n   * When provided, sets the x and y coordinates of the floating card.\n   */\n  initialPosition?: Readonly<{ x: number; y: 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 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoFrD,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

@@ -11,11 +11,66 @@
  */
 
 import { PropsWithChildren, ReactNode } from "react";
-import * as react_jsx_runtime69 from "react/jsx-runtime";
+import * as react_jsx_runtime64 from "react/jsx-runtime";
+import { UniqueId } from "@accelint/core/utility/uuid";
 
 //#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`. */
+/**
+ * A value that can be static or dynamically computed per floating card.
+ *
+ * Enables per-card customization of props by passing a factory function
+ * that receives the card ID and returns the appropriate value.
+ *
+ * @template T - The type of the static value or factory return type.
+ */
 type MaybeFactory<T> = T | ((cardId: string) => T);
+/**
+ * Configuration for header action buttons in floating cards.
+ *
+ * Can be a custom button (with icon and onClick), a visual separator ('divider'),
+ * or the built-in pin toggle ('pin').
+ *
+ * @remarks
+ * - Custom buttons: Rendered as icon buttons with your provided onClick handler
+ * - 'divider': Inserts a vertical divider between action groups
+ * - 'pin': Adds built-in pin toggle button (disables dragging when pinned)
+ *
+ * @example
+ * ```tsx
+ * const headerActions: FloatingCardHeaderAction[] = [
+ *   { icon: <SettingsIcon />, onClick: () => openSettings() },
+ *   'divider',
+ *   'pin'
+ * ];
+ * ```
+ */
+type FloatingCardHeaderAction = {
+  /** Icon to display in the action button */
+  icon: ReactNode;
+  /** Handler called when the action button is clicked */
+  onClick: () => void;
+} | 'divider' | 'pin';
+/**
+ * Props for the FloatingCardProvider component.
+ *
+ * Configures default icon and header actions for all floating cards. Both can be
+ * static values or factory functions that receive the card ID for per-card customization.
+ *
+ * @example
+ * ```tsx
+ * <FloatingCardProvider
+ *   icon={<AppIcon />}
+ *   headerActions={(cardId) => {
+ *     if (cardId === 'settings') {
+ *       return [{ icon: <CogIcon />, onClick: openSettings }, 'pin'];
+ *     }
+ *     return ['pin'];
+ *   }}
+ * >
+ *   {children}
+ * </FloatingCardProvider>
+ * ```
+ */
 type FloatingCardProviderProps = Readonly<PropsWithChildren<{
   /**
    * Optional icon rendered at the very start of the floating card header.
@@ -24,41 +79,63 @@ type FloatingCardProviderProps = Readonly<PropsWithChildren<{
   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 include `'divider'` to separate groups and `'pin'` to add a pin toggle button.
    * Can be an array or a function `(cardId: string) => array` to return
    * per-floating card actions.
    */
-  headerActions?: MaybeFactory<({
-    icon: ReactNode;
-    onClick: () => void;
-  } | 'divider')[]>;
+  headerActions?: MaybeFactory<FloatingCardHeaderAction[]>;
+  /**
+   * Optional set of card IDs that should be pinned when the provider first mounts.
+   *
+   * Like other `initial*` props, this value is only read once at mount time.
+   * Changes after mount have no effect.
+   */
+  initialPinned?: readonly UniqueId[];
+  /** Additional CSS class names for styling */
   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_runtime64.JSX.Element;
 //#endregion
-export { FloatingCardProvider, FloatingCardProviderProps };
+export { FloatingCardHeaderAction, FloatingCardProvider, FloatingCardProviderProps };
 //# sourceMappingURL=provider.d.ts.map