@accelint/design-toolkit 9.9.2 → 9.11.0

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

@@ -1 +1 @@
-{"version":3,"file":"provider.js","names":["CloseIcon","components: Record<string, FunctionComponent<IDockviewPanelProps>>"],"sources":["../../../src/components/floating-card/provider.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 { clsx } from '@accelint/design-foundation/lib/utils';\nimport CloseIcon from '@accelint/icons/cancel';\nimport {\n  type DockviewApi,\n  DockviewReact,\n  type DockviewReadyEvent,\n  type IDockviewHeaderActionsProps,\n  type IDockviewPanelProps,\n} from 'dockview-react';\nimport {\n  type FunctionComponent,\n  type PropsWithChildren,\n  type ReactNode,\n  useCallback,\n  useEffect,\n  useMemo,\n  useState,\n} from 'react';\nimport { Button } from '../button';\nimport { Divider } from '../divider';\nimport { Icon } from '../icon';\nimport {\n  FloatingCardContext,\n  type FloatingCardContextValue,\n  useFloatingCard,\n} from './context';\nimport styles from './styles.module.css';\nimport type { UniqueId } from '@accelint/core/utility/uuid';\n\n/** A value that is either `T` directly, or a function that receives the active card id and returns `T`. */\ntype MaybeFactory<T> = T | ((cardId: string) => T);\n\ntype FloatingCardHeaderProps = {\n  id?: string;\n  title?: string;\n  icon?: ReactNode;\n  closeGroup: () => void;\n  headerActions?: (\n    | {\n        icon: ReactNode;\n        onClick: () => void;\n      }\n    | 'divider'\n  )[];\n};\n\n/**\n * Internal component that registers a DOM ref for a card container.\n * Used by the floating card engine to mount portal targets.\n */\nfunction FloatingCardContainer(props: Readonly<IDockviewPanelProps>) {\n  const { addRef } = useFloatingCard();\n\n  const refCallback = useCallback(\n    (ref: HTMLDivElement | null) => {\n      addRef(props.api.id as UniqueId, ref);\n    },\n    [addRef, props.api.id],\n  );\n\n  return <div className={styles.cardContent} ref={refCallback} />;\n}\n\n/**\n * Default left header showing an optional custom icon (or a placeholder) and the card's title.\n */\nfunction DefaultLeftHeader({\n  title,\n  icon,\n  id,\n}: Readonly<FloatingCardHeaderProps>) {\n  return (\n    <div className={styles.headerSide}>\n      {icon ? <Icon size='small'>{icon}</Icon> : null}\n      {title && title !== id ? (\n        <div className={styles.headerTitle}>{title}</div>\n      ) : null}\n    </div>\n  );\n}\n\n/**\n * Default right header showing optional action buttons and an always-present close button.\n */\nfunction DefaultRightHeader({\n  closeGroup,\n  headerActions,\n  id,\n}: Readonly<FloatingCardHeaderProps>) {\n  return (\n    <div className={styles.headerSide}>\n      {headerActions?.map((action, index) => {\n        if (action === 'divider') {\n          return (\n            // biome-ignore lint/suspicious/noArrayIndexKey: Using index as key is acceptable here because the order of actions is unlikely to change.\n            <Divider key={`${id}-divider-${index}`} orientation='vertical' />\n          );\n        }\n        return (\n          <Button\n            key={`${id}-${\n              // biome-ignore lint/suspicious/noArrayIndexKey: Using index as key is acceptable here because the order of actions is unlikely to change.\n              index\n            }`}\n            variant='icon'\n            size='small'\n            onClick={action.onClick}\n          >\n            <Icon>{action.icon}</Icon>\n          </Button>\n        );\n      })}\n      <Button variant='icon' size='small' onClick={closeGroup}>\n        <Icon>\n          <CloseIcon />\n        </Icon>\n      </Button>\n    </div>\n  );\n}\n\ntype HeaderAdapterOptions = {\n  icon?: MaybeFactory<ReactNode>;\n  headerActions?: MaybeFactory<FloatingCardHeaderProps['headerActions']>;\n};\n\n/**\n * Creates an adapter component to map Dockview's header action props to our custom header component props.\n */\nfunction createHeaderAdapter(\n  Component: FunctionComponent<FloatingCardHeaderProps>,\n  options?: HeaderAdapterOptions,\n): FunctionComponent<IDockviewHeaderActionsProps> {\n  function HeaderAdapter(props: Readonly<IDockviewHeaderActionsProps>) {\n    const panelId = props.panels[0]?.id ?? '';\n    const [title, setTitle] = useState(props.activePanel?.title);\n\n    useEffect(() => {\n      const panel = props.activePanel;\n\n      if (!panel) {\n        return;\n      }\n\n      setTitle(panel.title);\n\n      const disposable = panel.api.onDidTitleChange(() => {\n        setTitle(panel.title);\n      });\n\n      return () => {\n        disposable.dispose();\n      };\n    }, [props.activePanel]);\n    const icon = props.activePanel\n      ? typeof options?.icon === 'function'\n        ? options.icon(panelId)\n        : options?.icon\n      : undefined;\n    const headerActions =\n      typeof options?.headerActions === 'function'\n        ? options.headerActions(panelId)\n        : options?.headerActions;\n    return (\n      <Component\n        icon={icon}\n        headerActions={headerActions}\n        title={title}\n        id={props.activePanel?.id}\n        closeGroup={() => props.api.close()}\n      />\n    );\n  }\n\n  HeaderAdapter.displayName = `HeaderAdapter(${Component.displayName ?? Component.name ?? 'Anonymous'})`;\n  return HeaderAdapter;\n}\n\nexport type FloatingCardProviderProps = Readonly<\n  PropsWithChildren<{\n    /**\n     * Optional icon rendered at the very start of the floating card header.\n     * Can be a `ReactNode` or a function `(cardId: string) => ReactNode`.\n     */\n    icon?: MaybeFactory<ReactNode>;\n    /**\n     * Optional action buttons rendered in the floating card header before the close button.\n     * Can include dividers to separate groups of actions.\n     * Can be an array or a function `(cardId: string) => array` to return\n     * per-floating card actions.\n     */\n    headerActions?: MaybeFactory<\n      (\n        | {\n            icon: ReactNode;\n            onClick: () => void;\n          }\n        | 'divider'\n      )[]\n    >;\n    className?: string;\n  }>\n>;\n\nconst components: Record<string, FunctionComponent<IDockviewPanelProps>> = {\n  default: FloatingCardContainer,\n};\n\n/**\n * Provides a context and layout area for floating cards within the application.\n *\n * Wraps its children with floating card context and renders a floating card engine instance\n * to manage docking and layout.\n *\n * @param props - The props for the FloatingCardProvider component.\n * @param props.children - Child components rendered inside the floating card provider.\n * @param props.icon - Optional icon.\n * @param props.headerActions - Optional actions for the header.\n * @param props.className - Additional CSS class names for styling.\n *\n * @returns The FloatingCardProvider component that manages floating card layout and context.\n *\n * @remarks\n * - Manages registration and unregistration of floating card references.\n * - Exposes `closeCard` via context for child components.\n * - Ensures floating cards are bounded within the viewport.\n */\nexport function FloatingCardProvider({\n  children,\n  icon,\n  headerActions,\n  className,\n}: FloatingCardProviderProps) {\n  const [api, setApi] = useState<DockviewApi | null>(null);\n  const [cards, setCards] = useState<Record<UniqueId, HTMLDivElement>>({});\n\n  const closeCard = useCallback(\n    (id: UniqueId) => {\n      api?.getPanel(id)?.api.close();\n    },\n    [api],\n  );\n\n  const removeRef = useCallback((view: UniqueId) => {\n    setCards((prev) => {\n      const newCards = { ...prev };\n      delete newCards[view];\n      return newCards;\n    });\n  }, []);\n\n  const addRef = useCallback((id: UniqueId, ref: HTMLDivElement | null) => {\n    if (ref) {\n      setCards((prev) => {\n        if (prev[id]) {\n          return prev;\n        }\n        return { ...prev, [id]: ref };\n      });\n    }\n  }, []);\n\n  // Clean up stale refs when cards are removed via any path\n  // (drag close, group close, API close, etc.)\n  useEffect(() => {\n    if (!api) {\n      return;\n    }\n\n    const disposable = api.onDidRemovePanel((event) => {\n      removeRef(event.id as UniqueId);\n    });\n\n    return () => {\n      disposable.dispose();\n    };\n  }, [api, removeRef]);\n\n  const contextValue = useMemo<FloatingCardContextValue>(\n    () => ({\n      cards,\n      addRef,\n      removeRef,\n      closeCard,\n      api,\n    }),\n    [cards, closeCard, removeRef, api, addRef],\n  );\n\n  const leftAdapter = useMemo(\n    () => createHeaderAdapter(DefaultLeftHeader, { icon }),\n    [icon],\n  );\n\n  const rightAdapter = useMemo(\n    () => createHeaderAdapter(DefaultRightHeader, { headerActions }),\n    [headerActions],\n  );\n\n  const theme = useMemo(\n    () => ({\n      name: 'accelint',\n      className: styles.floatingCardProvider ?? '',\n    }),\n    [],\n  );\n\n  const onReady = useCallback((event: DockviewReadyEvent) => {\n    setApi(event.api);\n  }, []);\n\n  return (\n    <FloatingCardContext.Provider value={contextValue}>\n      <div className={clsx(styles.providerRoot, className)}>\n        <DockviewReact\n          locked\n          floatingGroupBounds={'boundedWithinViewport'}\n          components={components}\n          prefixHeaderActionsComponent={leftAdapter}\n          rightHeaderActionsComponent={rightAdapter}\n          onReady={onReady}\n          theme={theme}\n        />\n        {children}\n      </div>\n    </FloatingCardContext.Provider>\n  );\n}\n"],"mappings":"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"}
+{"version":3,"file":"provider.js","names":["CloseIcon","components: Record<string, FunctionComponent<IDockviewPanelProps>>"],"sources":["../../../src/components/floating-card/provider.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 { clsx } from '@accelint/design-foundation/lib/utils';\nimport CloseIcon from '@accelint/icons/cancel';\nimport PinIcon from '@accelint/icons/pin';\nimport {\n  type DockviewApi,\n  DockviewReact,\n  type DockviewReadyEvent,\n  type IDockviewPanelProps,\n} from 'dockview-react';\nimport {\n  type FunctionComponent,\n  useCallback,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n  useSyncExternalStore,\n} from 'react';\nimport { Button } from '../button';\nimport { Divider } from '../divider';\nimport { Icon } from '../icon';\nimport { FloatingCardContext, useFloatingCard } from './context';\nimport styles from './styles.module.css';\nimport { createHeaderAdapter, type FloatingCardHeaderProps } from './utils';\nimport type { UniqueId } from '@accelint/core/utility/uuid';\nimport type {\n  FloatingCardContextValue,\n  FloatingCardProviderProps,\n} from './types';\n\n/**\n * Internal component that registers a DOM ref for a card container.\n *\n * Used by the floating card engine to mount portal targets. Also manages\n * the data-pinned attribute on the resize container to control drag handle visibility.\n *\n * @param props - Dockview panel props containing the card ID.\n */\nfunction FloatingCardContainer(props: Readonly<IDockviewPanelProps>) {\n  const { addRef, isPinned, subscribeToPinState } = useFloatingCard();\n  const cardId = props.api.id as UniqueId;\n\n  const pinned = useSyncExternalStore(\n    subscribeToPinState,\n    () => isPinned(cardId),\n    () => false,\n  );\n\n  const cardRef = useRef<HTMLDivElement | null>(null);\n\n  const refCallback = useCallback(\n    (ref: HTMLDivElement | null) => {\n      cardRef.current = ref;\n      addRef(cardId, ref);\n    },\n    [addRef, cardId],\n  );\n\n  // Toggle a data-pinned attribute on the ancestor .dv-resize-container\n  // so CSS can disable pointer-events on the drag handle.\n  useEffect(() => {\n    const el = cardRef.current;\n    const container = el?.closest<HTMLElement>('.dv-resize-container');\n\n    if (!container) {\n      return;\n    }\n\n    if (pinned) {\n      container.dataset.pinned = '';\n    } else {\n      delete container.dataset.pinned;\n    }\n  }, [pinned]);\n\n  return <div className={styles.cardContent} ref={refCallback} />;\n}\n\n/**\n * Default left header showing an optional custom icon and the card's title.\n */\nfunction DefaultLeftHeader({\n  title,\n  icon,\n  id,\n}: Readonly<FloatingCardHeaderProps>) {\n  return (\n    <div className={styles.headerSide}>\n      {icon ? <Icon size='small'>{icon}</Icon> : null}\n      {title && title !== id ? (\n        <div className={styles.headerTitleContainer}>\n          <div className={styles.headerTitle}>{title}</div>\n        </div>\n      ) : null}\n    </div>\n  );\n}\n\n/** Stable no-op subscribe for useSyncExternalStore when no pin subscription is available. */\nconst noopSubscribe = () => () => undefined;\n\n/**\n * Default right header showing optional action buttons and an always-present close button.\n *\n * @remarks Handles rendering of 'divider' and 'pin' action types specially.\n */\nfunction DefaultRightHeader({\n  closeGroup,\n  headerActions,\n  id,\n  togglePinCard,\n  isPinned,\n  subscribeToPinState,\n}: Readonly<FloatingCardHeaderProps>) {\n  const pinned = useSyncExternalStore(\n    subscribeToPinState ?? noopSubscribe,\n    () => (id && isPinned ? isPinned(id as UniqueId) : false),\n    () => false,\n  );\n\n  return (\n    <div className={styles.headerSide}>\n      {headerActions?.map((action, index) => {\n        if (action === 'divider') {\n          return (\n            // biome-ignore lint/suspicious/noArrayIndexKey: Using index as key is acceptable here because the order of actions is unlikely to change.\n            <Divider key={`${id}-divider-${index}`} orientation='vertical' />\n          );\n        }\n        if (action === 'pin') {\n          return (\n            <Button\n              className={styles.pinButton}\n              // biome-ignore lint/suspicious/noArrayIndexKey: Using index as key is acceptable here because the order of actions is unlikely to change.\n              key={`${id}-pin-${index}`}\n              variant='icon'\n              size='small'\n              color={pinned ? 'accent' : undefined}\n              aria-label='Pin'\n              aria-pressed={pinned}\n              onClick={() => {\n                if (id && togglePinCard) {\n                  togglePinCard(id as UniqueId);\n                }\n              }}\n            >\n              <Icon>\n                <PinIcon />\n              </Icon>\n            </Button>\n          );\n        }\n        return (\n          <Button\n            key={`${id}-${\n              // biome-ignore lint/suspicious/noArrayIndexKey: Using index as key is acceptable here because the order of actions is unlikely to change.\n              index\n            }`}\n            variant='icon'\n            size='small'\n            onClick={action.onClick}\n          >\n            <Icon>{action.icon}</Icon>\n          </Button>\n        );\n      })}\n      <Button variant='icon' size='small' onClick={closeGroup}>\n        <Icon>\n          <CloseIcon />\n        </Icon>\n      </Button>\n    </div>\n  );\n}\n\nconst components: Record<string, FunctionComponent<IDockviewPanelProps>> = {\n  default: FloatingCardContainer,\n};\n\n/**\n * Provides a context and layout area for floating cards within the application.\n *\n * Wraps children with floating card context and renders a Dockview instance to manage\n * docking, dragging, and layout of floating cards.\n *\n * @param props - The props for the FloatingCardProvider component.\n * @param props.children - Child components rendered inside the floating card provider.\n * @param props.icon - Optional icon rendered in all card headers (static or factory).\n * @param props.headerActions - Optional action buttons for card headers (static or factory).\n * @param props.className - Additional CSS class names for styling.\n * @returns The FloatingCardProvider component that manages floating card layout and context.\n *\n * @remarks\n * - Manages registration and cleanup of floating card DOM references\n * - Exposes closeCard, togglePinCard, and isPinned via context\n * - Automatically cleans up refs when cards are removed via any path (drag close, group close, API close)\n * - Cards are bounded within the viewport\n *\n * @example\n * ```tsx\n * <FloatingCardProvider\n *   icon={<AppLogo />}\n *   headerActions={[\n *     { icon: <SettingsIcon />, onClick: openSettings },\n *     'divider',\n *     'pin'\n *   ]}\n * >\n *   <FloatingCard id=\"panel-1\" title=\"My Panel\">\n *     <div>Panel content</div>\n *   </FloatingCard>\n * </FloatingCardProvider>\n * ```\n */\nexport function FloatingCardProvider({\n  children,\n  icon,\n  headerActions,\n  initialPinned,\n  className,\n}: FloatingCardProviderProps) {\n  const [api, setApi] = useState<DockviewApi | null>(null);\n  const [cards, setCards] = useState<Record<UniqueId, HTMLDivElement>>({});\n  const pinnedCardsRef = useRef<Set<UniqueId>>(new Set(initialPinned));\n  const pinListenersRef = useRef<Set<() => void>>(new Set());\n\n  const closeCard = useCallback(\n    (id: UniqueId) => {\n      api?.getPanel(id)?.api.close();\n    },\n    [api],\n  );\n\n  const togglePinCard = useCallback((id: UniqueId) => {\n    const next = new Set(pinnedCardsRef.current);\n    if (next.has(id)) {\n      next.delete(id);\n    } else {\n      next.add(id);\n    }\n    pinnedCardsRef.current = next;\n    for (const listener of pinListenersRef.current) {\n      listener();\n    }\n  }, []);\n\n  const isPinned = useCallback(\n    (id: UniqueId) => pinnedCardsRef.current.has(id),\n    [],\n  );\n\n  const subscribeToPinState = useCallback((callback: () => void) => {\n    pinListenersRef.current.add(callback);\n    return () => {\n      pinListenersRef.current.delete(callback);\n    };\n  }, []);\n\n  const removeRef = useCallback((view: UniqueId) => {\n    setCards((prev) => {\n      const newCards = { ...prev };\n      delete newCards[view];\n      return newCards;\n    });\n    if (pinnedCardsRef.current.has(view)) {\n      const next = new Set(pinnedCardsRef.current);\n      next.delete(view);\n      pinnedCardsRef.current = next;\n      for (const listener of pinListenersRef.current) {\n        listener();\n      }\n    }\n  }, []);\n\n  const addRef = useCallback((id: UniqueId, ref: HTMLDivElement | null) => {\n    if (ref) {\n      setCards((prev) => {\n        if (prev[id]) {\n          return prev;\n        }\n        return { ...prev, [id]: ref };\n      });\n    }\n  }, []);\n\n  // Clean up stale refs when cards are removed via any path\n  // (drag close, group close, API close, etc.)\n  useEffect(() => {\n    if (!api) {\n      return;\n    }\n\n    const disposable = api.onDidRemovePanel((event) => {\n      removeRef(event.id as UniqueId);\n    });\n\n    return () => {\n      disposable.dispose();\n    };\n  }, [api, removeRef]);\n\n  const contextValue = useMemo<FloatingCardContextValue>(\n    () => ({\n      cards,\n      addRef,\n      removeRef,\n      closeCard,\n      togglePinCard,\n      isPinned,\n      subscribeToPinState,\n      api,\n    }),\n    [\n      cards,\n      closeCard,\n      removeRef,\n      api,\n      addRef,\n      togglePinCard,\n      isPinned,\n      subscribeToPinState,\n    ],\n  );\n\n  const leftAdapter = useMemo(\n    () =>\n      createHeaderAdapter(DefaultLeftHeader, {\n        icon,\n      }),\n    [icon],\n  );\n\n  const rightAdapter = useMemo(\n    () =>\n      createHeaderAdapter(DefaultRightHeader, {\n        headerActions,\n        togglePinCard,\n        isPinned,\n        subscribeToPinState,\n      }),\n    [headerActions, togglePinCard, isPinned, subscribeToPinState],\n  );\n\n  const theme = useMemo(\n    () => ({\n      name: 'accelint',\n      className: styles.floatingCardProvider ?? '',\n    }),\n    [],\n  );\n\n  const onReady = useCallback((event: DockviewReadyEvent) => {\n    setApi(event.api);\n  }, []);\n\n  return (\n    <FloatingCardContext.Provider value={contextValue}>\n      <div className={clsx(styles.providerRoot, className)}>\n        <DockviewReact\n          locked\n          floatingGroupBounds={'boundedWithinViewport'}\n          components={components}\n          prefixHeaderActionsComponent={leftAdapter}\n          rightHeaderActionsComponent={rightAdapter}\n          onReady={onReady}\n          theme={theme}\n        />\n        {children}\n      </div>\n    </FloatingCardContext.Provider>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkDA,SAAS,sBAAsB,OAAsC;CACnE,MAAM,EAAE,QAAQ,UAAU,wBAAwB,iBAAiB;CACnE,MAAM,SAAS,MAAM,IAAI;CAEzB,MAAM,SAAS,qBACb,2BACM,SAAS,OAAO,QAChB,MACP;CAED,MAAM,UAAU,OAA8B,KAAK;CAEnD,MAAM,cAAc,aACjB,QAA+B;AAC9B,UAAQ,UAAU;AAClB,SAAO,QAAQ,IAAI;IAErB,CAAC,QAAQ,OAAO,CACjB;AAID,iBAAgB;EAEd,MAAM,YADK,QAAQ,SACG,QAAqB,uBAAuB;AAElE,MAAI,CAAC,UACH;AAGF,MAAI,OACF,WAAU,QAAQ,SAAS;MAE3B,QAAO,UAAU,QAAQ;IAE1B,CAAC,OAAO,CAAC;AAEZ,QAAO,oBAAC;EAAI,WAAW,OAAO;EAAa,KAAK;GAAe;;;;;AAMjE,SAAS,kBAAkB,EACzB,OACA,MACA,MACoC;AACpC,QACE,qBAAC;EAAI,WAAW,OAAO;aACpB,OAAO,oBAAC;GAAK,MAAK;aAAS;IAAY,GAAG,MAC1C,SAAS,UAAU,KAClB,oBAAC;GAAI,WAAW,OAAO;aACrB,oBAAC;IAAI,WAAW,OAAO;cAAc;KAAY;IAC7C,GACJ;GACA;;;AAKV,MAAM,4BAA4B;;;;;;AAOlC,SAAS,mBAAmB,EAC1B,YACA,eACA,IACA,eACA,UACA,uBACoC;CACpC,MAAM,SAAS,qBACb,uBAAuB,qBAChB,MAAM,WAAW,SAAS,GAAe,GAAG,aAC7C,MACP;AAED,QACE,qBAAC;EAAI,WAAW,OAAO;aACpB,eAAe,KAAK,QAAQ,UAAU;AACrC,OAAI,WAAW,UACb,QAEE,oBAAC,WAAuC,aAAY,cAAtC,GAAG,GAAG,WAAW,QAAkC;AAGrE,OAAI,WAAW,MACb,QACE,oBAAC;IACC,WAAW,OAAO;IAGlB,SAAQ;IACR,MAAK;IACL,OAAO,SAAS,WAAW;IAC3B,cAAW;IACX,gBAAc;IACd,eAAe;AACb,SAAI,MAAM,cACR,eAAc,GAAe;;cAIjC,oBAAC,kBACC,oBAAC,YAAU,GACN;MAdF,GAAG,GAAG,OAAO,QAeX;AAGb,UACE,oBAAC;IAKC,SAAQ;IACR,MAAK;IACL,SAAS,OAAO;cAEhB,oBAAC,kBAAM,OAAO,OAAY;MARrB,GAAG,GAAG,GAET,QAOK;IAEX,EACF,oBAAC;GAAO,SAAQ;GAAO,MAAK;GAAQ,SAAS;aAC3C,oBAAC,kBACC,oBAACA,WAAY,GACR;IACA;GACL;;AAIV,MAAMC,aAAqE,EACzE,SAAS,uBACV;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCD,SAAgB,qBAAqB,EACnC,UACA,MACA,eACA,eACA,aAC4B;CAC5B,MAAM,CAAC,KAAK,UAAU,SAA6B,KAAK;CACxD,MAAM,CAAC,OAAO,YAAY,SAA2C,EAAE,CAAC;CACxE,MAAM,iBAAiB,OAAsB,IAAI,IAAI,cAAc,CAAC;CACpE,MAAM,kBAAkB,uBAAwB,IAAI,KAAK,CAAC;CAE1D,MAAM,YAAY,aACf,OAAiB;AAChB,OAAK,SAAS,GAAG,EAAE,IAAI,OAAO;IAEhC,CAAC,IAAI,CACN;CAED,MAAM,gBAAgB,aAAa,OAAiB;EAClD,MAAM,OAAO,IAAI,IAAI,eAAe,QAAQ;AAC5C,MAAI,KAAK,IAAI,GAAG,CACd,MAAK,OAAO,GAAG;MAEf,MAAK,IAAI,GAAG;AAEd,iBAAe,UAAU;AACzB,OAAK,MAAM,YAAY,gBAAgB,QACrC,WAAU;IAEX,EAAE,CAAC;CAEN,MAAM,WAAW,aACd,OAAiB,eAAe,QAAQ,IAAI,GAAG,EAChD,EAAE,CACH;CAED,MAAM,sBAAsB,aAAa,aAAyB;AAChE,kBAAgB,QAAQ,IAAI,SAAS;AACrC,eAAa;AACX,mBAAgB,QAAQ,OAAO,SAAS;;IAEzC,EAAE,CAAC;CAEN,MAAM,YAAY,aAAa,SAAmB;AAChD,YAAU,SAAS;GACjB,MAAM,WAAW,EAAE,GAAG,MAAM;AAC5B,UAAO,SAAS;AAChB,UAAO;IACP;AACF,MAAI,eAAe,QAAQ,IAAI,KAAK,EAAE;GACpC,MAAM,OAAO,IAAI,IAAI,eAAe,QAAQ;AAC5C,QAAK,OAAO,KAAK;AACjB,kBAAe,UAAU;AACzB,QAAK,MAAM,YAAY,gBAAgB,QACrC,WAAU;;IAGb,EAAE,CAAC;CAEN,MAAM,SAAS,aAAa,IAAc,QAA+B;AACvE,MAAI,IACF,WAAU,SAAS;AACjB,OAAI,KAAK,IACP,QAAO;AAET,UAAO;IAAE,GAAG;KAAO,KAAK;IAAK;IAC7B;IAEH,EAAE,CAAC;AAIN,iBAAgB;AACd,MAAI,CAAC,IACH;EAGF,MAAM,aAAa,IAAI,kBAAkB,UAAU;AACjD,aAAU,MAAM,GAAe;IAC/B;AAEF,eAAa;AACX,cAAW,SAAS;;IAErB,CAAC,KAAK,UAAU,CAAC;CAEpB,MAAM,eAAe,eACZ;EACL;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACD,GACD;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACD,CACF;CAED,MAAM,cAAc,cAEhB,oBAAoB,mBAAmB,EACrC,MACD,CAAC,EACJ,CAAC,KAAK,CACP;CAED,MAAM,eAAe,cAEjB,oBAAoB,oBAAoB;EACtC;EACA;EACA;EACA;EACD,CAAC,EACJ;EAAC;EAAe;EAAe;EAAU;EAAoB,CAC9D;CAED,MAAM,QAAQ,eACL;EACL,MAAM;EACN,WAAW,OAAO,wBAAwB;EAC3C,GACD,EAAE,CACH;CAED,MAAM,UAAU,aAAa,UAA8B;AACzD,SAAO,MAAM,IAAI;IAChB,EAAE,CAAC;AAEN,QACE,oBAAC,oBAAoB;EAAS,OAAO;YACnC,qBAAC;GAAI,WAAW,KAAK,OAAO,cAAc,UAAU;cAClD,oBAAC;IACC;IACA,qBAAqB;IACT;IACZ,8BAA8B;IAC9B,6BAA6B;IACpB;IACF;KACP,EACD;IACG;GACuB"}

package/dist/components/floating-card/styles.module.css

@@ -25,8 +25,21 @@
     @apply gap-xs flex h-full items-center;
   }
 
+  /* Zero width + pointer-events-none lets the title visually overflow the
+     flex row without consuming drag-handle space or intercepting pointer
+     gestures meant for dockview's drag handle (.dv-void-container). */
+  .headerTitleContainer {
+    @apply text-header-m pl-xs pointer-events-none h-full w-0;
+  }
+
+  /* Explicit width based on the header's container query width so long titles
+     truncate within the header rather than pushing siblings or overflowing.
+     The 10rem reserves space for the leading icon, header padding, gap, and
+     right-side action buttons; adjust when those change.
+     The @min-[1rem]/floating-card-header variant scopes the rule to cases
+     where the named container exists, so cqw never falls back to the viewport. */
   .headerTitle {
-    @apply text-header-m pl-xs;
+    @apply h-full truncate leading-24 @min-[1rem]/floating-card-header:w-[calc(100cqw-10rem)];
   }
 
   .floatingCardProvider {
@@ -48,7 +61,7 @@
 
     :global(.dv-tabs-and-actions-container) {
       --dv-tabs-and-actions-container-height: 32px;
-      @apply p-xs text-header-m;
+      @apply p-xs text-header-m @container/floating-card-header;
     }
     :global(.dv-scrollable) {
       display: none;
@@ -56,5 +69,10 @@
     :global(.dv-void-container) {
       cursor: grab;
     }
+
+    :global(.dv-resize-container[data-pinned]) :global(.dv-void-container) {
+      pointer-events: none;
+      cursor: default;
+    }
   }
 }

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

@@ -0,0 +1,161 @@
+/*
+ * Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { MaybeFactory } from "./utils.js";
+import { PropsWithChildren, ReactNode } from "react";
+import { DockviewApi } from "dockview-react";
+import { UniqueId } from "@accelint/core/utility/uuid";
+
+//#region src/components/floating-card/types.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;
+};
+/**
+ * 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.
+   *
+   * 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;
+  }>;
+  /**
+   * 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;
+  }>;
+}>;
+/**
+ * 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.
+   * 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 `'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<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;
+}>>;
+//#endregion
+export { FloatingCardContextValue, FloatingCardHeaderAction, FloatingCardProps, FloatingCardProviderProps };
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1,12 @@
+/*
+ * Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+

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

@@ -0,0 +1,104 @@
+/*
+ * Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { FloatingCardHeaderAction } from "./types.js";
+import { FunctionComponent, ReactNode } from "react";
+import { IDockviewHeaderActionsProps } from "dockview-react";
+import { UniqueId } from "@accelint/core/utility/uuid";
+
+//#region src/components/floating-card/utils.d.ts
+/**
+ * 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 options passed to floating card header adapter functions.
+ *
+ * Used internally by the floating card system to provide header components
+ * with the necessary props and callbacks for rendering customizable headers.
+ *
+ * @remarks
+ * This type is primarily used when creating custom header adapters that need
+ * access to icon, actions, and pin state management from the FloatingCardProvider.
+ *
+ * @example
+ * ```tsx
+ * function createHeaderAdapter(options: HeaderAdapterOptions) {
+ *   return (props: DockviewHeaderProps) => {
+ *     const icon = typeof options.icon === 'function'
+ *       ? options.icon(props.id)
+ *       : options.icon;
+ *     const actions = typeof options.headerActions === 'function'
+ *       ? options.headerActions(props.id)
+ *       : options.headerActions;
+ *
+ *     return (
+ *       <CustomHeader
+ *         icon={icon}
+ *         actions={actions}
+ *         isPinned={options.isPinned?.(props.id)}
+ *         onTogglePin={() => options.togglePinCard?.(props.id)}
+ *       />
+ *     );
+ *   };
+ * }
+ * ```
+ */
+type HeaderAdapterOptions = {
+  icon?: MaybeFactory<ReactNode>;
+  headerActions?: MaybeFactory<FloatingCardHeaderProps['headerActions']>;
+  togglePinCard?: (id: UniqueId) => void;
+  isPinned?: (id: UniqueId) => boolean;
+  subscribeToPinState?: (callback: () => void) => () => void;
+};
+/**
+ * Props passed to floating card header components.
+ *
+ * @remarks Internal type used by header adapters to map Dockview props to custom header components.
+ */
+type FloatingCardHeaderProps = {
+  /** ID of the active floating card panel */
+  id?: string;
+  /** Title text displayed in the header */
+  title?: string;
+  /** Optional icon displayed at the start of the header */
+  icon?: ReactNode;
+  /** Callback to close the entire card group */
+  closeGroup: () => void;
+  /** Toggles pin state for the specified card */
+  togglePinCard?: (id: UniqueId) => void;
+  /** Checks if the specified card is pinned */
+  isPinned?: (id: UniqueId) => boolean;
+  /** Subscribes to pin state changes; returns an unsubscribe function */
+  subscribeToPinState?: (callback: () => void) => () => void;
+  /** Custom action buttons to render in the header */
+  headerActions?: FloatingCardHeaderAction[];
+};
+/**
+ * Creates an adapter component to map Dockview's header action props to custom header component props.
+ *
+ * Handles title change subscriptions and resolves MaybeFactory options (icon, headerActions)
+ * either as static values or by invoking factory functions with the active card ID.
+ *
+ * @param Component - The header component to wrap.
+ * @param options - Configuration options including icon and headerActions (static or factory).
+ * @returns Adapter component compatible with Dockview's header API.
+ */
+declare function createHeaderAdapter(Component: FunctionComponent<FloatingCardHeaderProps>, options: HeaderAdapterOptions): FunctionComponent<IDockviewHeaderActionsProps>;
+//#endregion
+export { FloatingCardHeaderProps, MaybeFactory, createHeaderAdapter };
+//# sourceMappingURL=utils.d.ts.map

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

@@ -0,0 +1,60 @@
+/*
+ * Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+
+import { useEffect, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/components/floating-card/utils.tsx
+/**
+* Creates an adapter component to map Dockview's header action props to custom header component props.
+*
+* Handles title change subscriptions and resolves MaybeFactory options (icon, headerActions)
+* either as static values or by invoking factory functions with the active card ID.
+*
+* @param Component - The header component to wrap.
+* @param options - Configuration options including icon and headerActions (static or factory).
+* @returns Adapter component compatible with Dockview's header API.
+*/
+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(),
+			togglePinCard: options.togglePinCard,
+			isPinned: options.isPinned,
+			subscribeToPinState: options.subscribeToPinState
+		});
+	}
+	HeaderAdapter.displayName = `HeaderAdapter(${Component.displayName ?? Component.name ?? "Anonymous"})`;
+	return HeaderAdapter;
+}
+
+//#endregion
+export { createHeaderAdapter };
+//# sourceMappingURL=utils.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","names":[],"sources":["../../../src/components/floating-card/utils.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 {\n  type FunctionComponent,\n  type ReactNode,\n  useEffect,\n  useState,\n} from 'react';\nimport type { UniqueId } from '@accelint/core/utility/uuid';\nimport type { IDockviewHeaderActionsProps } from 'dockview-react';\nimport type { FloatingCardHeaderAction } from './types';\n\n/**\n * A value that can be static or dynamically computed per floating card.\n *\n * Enables per-card customization of props by passing a factory function\n * that receives the card ID and returns the appropriate value.\n *\n * @template T - The type of the static value or factory return type.\n */\nexport type MaybeFactory<T> = T | ((cardId: string) => T);\n\n/**\n * Configuration options passed to floating card header adapter functions.\n *\n * Used internally by the floating card system to provide header components\n * with the necessary props and callbacks for rendering customizable headers.\n *\n * @remarks\n * This type is primarily used when creating custom header adapters that need\n * access to icon, actions, and pin state management from the FloatingCardProvider.\n *\n * @example\n * ```tsx\n * function createHeaderAdapter(options: HeaderAdapterOptions) {\n *   return (props: DockviewHeaderProps) => {\n *     const icon = typeof options.icon === 'function'\n *       ? options.icon(props.id)\n *       : options.icon;\n *     const actions = typeof options.headerActions === 'function'\n *       ? options.headerActions(props.id)\n *       : options.headerActions;\n *\n *     return (\n *       <CustomHeader\n *         icon={icon}\n *         actions={actions}\n *         isPinned={options.isPinned?.(props.id)}\n *         onTogglePin={() => options.togglePinCard?.(props.id)}\n *       />\n *     );\n *   };\n * }\n * ```\n */\ntype HeaderAdapterOptions = {\n  icon?: MaybeFactory<ReactNode>;\n  headerActions?: MaybeFactory<FloatingCardHeaderProps['headerActions']>;\n  togglePinCard?: (id: UniqueId) => void;\n  isPinned?: (id: UniqueId) => boolean;\n  subscribeToPinState?: (callback: () => void) => () => void;\n};\n\n/**\n * Props passed to floating card header components.\n *\n * @remarks Internal type used by header adapters to map Dockview props to custom header components.\n */\nexport type FloatingCardHeaderProps = {\n  /** ID of the active floating card panel */\n  id?: string;\n  /** Title text displayed in the header */\n  title?: string;\n  /** Optional icon displayed at the start of the header */\n  icon?: ReactNode;\n  /** Callback to close the entire card group */\n  closeGroup: () => void;\n  /** Toggles pin state for the specified card */\n  togglePinCard?: (id: UniqueId) => void;\n  /** Checks if the specified card is pinned */\n  isPinned?: (id: UniqueId) => boolean;\n  /** Subscribes to pin state changes; returns an unsubscribe function */\n  subscribeToPinState?: (callback: () => void) => () => void;\n  /** Custom action buttons to render in the header */\n  headerActions?: FloatingCardHeaderAction[];\n};\n\n/**\n * Creates an adapter component to map Dockview's header action props to custom header component props.\n *\n * Handles title change subscriptions and resolves MaybeFactory options (icon, headerActions)\n * either as static values or by invoking factory functions with the active card ID.\n *\n * @param Component - The header component to wrap.\n * @param options - Configuration options including icon and headerActions (static or factory).\n * @returns Adapter component compatible with Dockview's header API.\n */\nexport function createHeaderAdapter(\n  Component: FunctionComponent<FloatingCardHeaderProps>,\n  options: HeaderAdapterOptions,\n): FunctionComponent<IDockviewHeaderActionsProps> {\n  function HeaderAdapter(props: Readonly<IDockviewHeaderActionsProps>) {\n    const panelId = props.panels[0]?.id ?? '';\n    const [title, setTitle] = useState(props.activePanel?.title);\n\n    useEffect(() => {\n      const panel = props.activePanel;\n\n      if (!panel) {\n        return;\n      }\n\n      setTitle(panel.title);\n\n      const disposable = panel.api.onDidTitleChange(() => {\n        setTitle(panel.title);\n      });\n\n      return () => {\n        disposable.dispose();\n      };\n    }, [props.activePanel]);\n    const icon = props.activePanel\n      ? typeof options?.icon === 'function'\n        ? options.icon(panelId)\n        : options?.icon\n      : undefined;\n    const headerActions =\n      typeof options?.headerActions === 'function'\n        ? options.headerActions(panelId)\n        : options?.headerActions;\n    return (\n      <Component\n        icon={icon}\n        headerActions={headerActions}\n        title={title}\n        id={props.activePanel?.id}\n        closeGroup={() => props.api.close()}\n        togglePinCard={options.togglePinCard}\n        isPinned={options.isPinned}\n        subscribeToPinState={options.subscribeToPinState}\n      />\n    );\n  }\n\n  HeaderAdapter.displayName = `HeaderAdapter(${Component.displayName ?? Component.name ?? 'Anonymous'})`;\n  return HeaderAdapter;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA4GA,SAAgB,oBACd,WACA,SACgD;CAChD,SAAS,cAAc,OAA8C;EACnE,MAAM,UAAU,MAAM,OAAO,IAAI,MAAM;EACvC,MAAM,CAAC,OAAO,YAAY,SAAS,MAAM,aAAa,MAAM;AAE5D,kBAAgB;GACd,MAAM,QAAQ,MAAM;AAEpB,OAAI,CAAC,MACH;AAGF,YAAS,MAAM,MAAM;GAErB,MAAM,aAAa,MAAM,IAAI,uBAAuB;AAClD,aAAS,MAAM,MAAM;KACrB;AAEF,gBAAa;AACX,eAAW,SAAS;;KAErB,CAAC,MAAM,YAAY,CAAC;AAUvB,SACE,oBAAC;GACC,MAXS,MAAM,cACf,OAAO,SAAS,SAAS,aACvB,QAAQ,KAAK,QAAQ,GACrB,SAAS,OACX;GAQA,eANF,OAAO,SAAS,kBAAkB,aAC9B,QAAQ,cAAc,QAAQ,GAC9B,SAAS;GAKJ;GACP,IAAI,MAAM,aAAa;GACvB,kBAAkB,MAAM,IAAI,OAAO;GACnC,eAAe,QAAQ;GACvB,UAAU,QAAQ;GAClB,qBAAqB,QAAQ;IAC7B;;AAIN,eAAc,cAAc,iBAAiB,UAAU,eAAe,UAAU,QAAQ,YAAY;AACpG,QAAO"}

package/dist/components/gantt/components/base-elements/point.d.ts

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { GanttRowElementColorProp } from "../../types.js";
+import { HTMLAttributes, PropsWithChildren } from "react";
+import * as react_jsx_runtime235 from "react/jsx-runtime";
+
+//#region src/components/gantt/components/base-elements/point.d.ts
+/** Props for point-based Gantt elements (markers, brackets). */
+type PointProps = HTMLAttributes<HTMLDivElement> & {
+  /** Timestamp in epoch milliseconds for the point position on the timeline. */
+  timeMs: number;
+  /** Visual color variant. @default 'accent' */
+  color?: GanttRowElementColorProp;
+};
+declare function Point(props: PropsWithChildren<PointProps>): react_jsx_runtime235.JSX.Element | null;
+//#endregion
+export { Point, PointProps };
+//# sourceMappingURL=point.d.ts.map

package/dist/components/gantt/components/base-elements/point.js

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+
+import { timestampWithinBounds } from "../../utils/helpers.js";
+import { useTemporalDataContext } from "../../context/temporal-data/index.js";
+import { usePointElementLayout } from "./use-point-element-layout/index.js";
+import { useCallback, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/components/gantt/components/base-elements/point.tsx
+function PointInner({ children, timeMs, color = "accent", ...rest }) {
+	const [element, setElement] = useState(null);
+	usePointElementLayout({
+		element,
+		timeMs
+	});
+	return /* @__PURE__ */ jsx("div", {
+		ref: useCallback((node) => {
+			setElement(node);
+		}, []),
+		"data-color": color,
+		...rest,
+		children
+	});
+}
+function Point(props) {
+	const { renderedRegionBounds } = useTemporalDataContext();
+	if (!timestampWithinBounds(props.timeMs, renderedRegionBounds)) return null;
+	return /* @__PURE__ */ jsx(PointInner, { ...props });
+}
+
+//#endregion
+export { Point };
+//# sourceMappingURL=point.js.map

package/dist/components/gantt/components/base-elements/point.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"point.js","names":[],"sources":["../../../../../src/components/gantt/components/base-elements/point.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 {\n  type HTMLAttributes,\n  type PropsWithChildren,\n  useCallback,\n  useState,\n} from 'react';\nimport { useTemporalDataContext } from '@/components/gantt/context/temporal-data';\nimport { timestampWithinBounds } from '@/components/gantt/utils/helpers';\nimport { usePointElementLayout } from './use-point-element-layout';\nimport type { GanttRowElementColorProp } from '@/components/gantt/types';\n\n/** Props for point-based Gantt elements (markers, brackets). */\nexport type PointProps = HTMLAttributes<HTMLDivElement> & {\n  /** Timestamp in epoch milliseconds for the point position on the timeline. */\n  timeMs: number;\n  /** Visual color variant. @default 'accent' */\n  color?: GanttRowElementColorProp;\n};\n\nfunction PointInner({\n  children,\n  timeMs,\n  color = 'accent',\n  ...rest\n}: PropsWithChildren<PointProps>) {\n  const [element, setElement] = useState<HTMLDivElement | null>(null);\n\n  usePointElementLayout({\n    element,\n    timeMs,\n  });\n\n  const assignElementRef = useCallback((node: HTMLDivElement | null) => {\n    setElement(node);\n  }, []);\n\n  return (\n    <div ref={assignElementRef} data-color={color} {...rest}>\n      {children}\n    </div>\n  );\n}\n\nexport function Point(props: PropsWithChildren<PointProps>) {\n  const { renderedRegionBounds } = useTemporalDataContext();\n\n  if (!timestampWithinBounds(props.timeMs, renderedRegionBounds)) {\n    return null;\n  }\n\n  return <PointInner {...props} />;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAgCA,SAAS,WAAW,EAClB,UACA,QACA,QAAQ,UACR,GAAG,QAC6B;CAChC,MAAM,CAAC,SAAS,cAAc,SAAgC,KAAK;AAEnE,uBAAsB;EACpB;EACA;EACD,CAAC;AAMF,QACE,oBAAC;EAAI,KALkB,aAAa,SAAgC;AACpE,cAAW,KAAK;KACf,EAAE,CAAC;EAGwB,cAAY;EAAO,GAAI;EAChD;GACG;;AAIV,SAAgB,MAAM,OAAsC;CAC1D,MAAM,EAAE,yBAAyB,wBAAwB;AAEzD,KAAI,CAAC,sBAAsB,MAAM,QAAQ,qBAAqB,CAC5D,QAAO;AAGT,QAAO,oBAAC,cAAW,GAAI,QAAS"}

package/dist/components/gantt/components/base-elements/range.d.ts

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { GanttRowElementColorProp } from "../../types.js";
+import { HTMLAttributes, PropsWithChildren } from "react";
+import * as react_jsx_runtime220 from "react/jsx-runtime";
+
+//#region src/components/gantt/components/base-elements/range.d.ts
+/** Props for range-based Gantt elements (blocks, spacers). */
+type RangeProps = HTMLAttributes<HTMLDivElement> & {
+  /** Start timestamp in epoch milliseconds for the range element. */
+  startTimeMs: number;
+  /** End timestamp in epoch milliseconds for the range element. */
+  endTimeMs: number;
+  /** Visual color variant. @default 'accent' */
+  color?: GanttRowElementColorProp;
+};
+declare function Range(props: PropsWithChildren<RangeProps>): react_jsx_runtime220.JSX.Element | null;
+//#endregion
+export { Range, RangeProps };
+//# sourceMappingURL=range.d.ts.map

package/dist/components/gantt/components/base-elements/range.js

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+
+import { shouldRenderRangeElement } from "../../utils/helpers.js";
+import { useTemporalDataContext } from "../../context/temporal-data/index.js";
+import { useRangeElementLayout } from "./use-range-element-layout/index.js";
+import { useCallback, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/components/gantt/components/base-elements/range.tsx
+function RangeInner({ children, startTimeMs, endTimeMs, color = "accent", ...rest }) {
+	const [element, setElement] = useState(null);
+	useRangeElementLayout({
+		element,
+		timeBounds: {
+			startMs: startTimeMs,
+			endMs: endTimeMs
+		}
+	});
+	return /* @__PURE__ */ jsx("div", {
+		ref: useCallback((node) => {
+			setElement(node);
+		}, []),
+		"data-color": color,
+		...rest,
+		children
+	});
+}
+function Range(props) {
+	const { renderedRegionBounds } = useTemporalDataContext();
+	const { startTimeMs, endTimeMs } = props;
+	if (!shouldRenderRangeElement(renderedRegionBounds, {
+		startMs: startTimeMs,
+		endMs: endTimeMs
+	})) return null;
+	return /* @__PURE__ */ jsx(RangeInner, { ...props });
+}
+
+//#endregion
+export { Range };
+//# sourceMappingURL=range.js.map

package/dist/components/gantt/components/base-elements/range.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"range.js","names":[],"sources":["../../../../../src/components/gantt/components/base-elements/range.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 {\n  type HTMLAttributes,\n  type PropsWithChildren,\n  useCallback,\n  useState,\n} from 'react';\nimport { useTemporalDataContext } from '@/components/gantt/context/temporal-data';\nimport { shouldRenderRangeElement } from '@/components/gantt/utils/helpers';\nimport { useRangeElementLayout } from './use-range-element-layout';\nimport type { GanttRowElementColorProp } from '@/components/gantt/types';\n\n/** Props for range-based Gantt elements (blocks, spacers). */\nexport type RangeProps = HTMLAttributes<HTMLDivElement> & {\n  /** Start timestamp in epoch milliseconds for the range element. */\n  startTimeMs: number;\n  /** End timestamp in epoch milliseconds for the range element. */\n  endTimeMs: number;\n  /** Visual color variant. @default 'accent' */\n  color?: GanttRowElementColorProp;\n};\n\nfunction RangeInner({\n  children,\n  startTimeMs,\n  endTimeMs,\n  color = 'accent',\n  ...rest\n}: PropsWithChildren<RangeProps>) {\n  const [element, setElement] = useState<HTMLDivElement | null>(null);\n\n  useRangeElementLayout({\n    element,\n    timeBounds: {\n      startMs: startTimeMs,\n      endMs: endTimeMs,\n    },\n  });\n\n  const assignElementRef = useCallback((node: HTMLDivElement | null) => {\n    setElement(node);\n  }, []);\n\n  return (\n    <div ref={assignElementRef} data-color={color} {...rest}>\n      {children}\n    </div>\n  );\n}\n\nexport function Range(props: PropsWithChildren<RangeProps>) {\n  const { renderedRegionBounds } = useTemporalDataContext();\n  const { startTimeMs, endTimeMs } = props;\n\n  if (\n    !shouldRenderRangeElement(renderedRegionBounds, {\n      startMs: startTimeMs,\n      endMs: endTimeMs,\n    })\n  ) {\n    return null;\n  }\n\n  return <RangeInner {...props} />;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAkCA,SAAS,WAAW,EAClB,UACA,aACA,WACA,QAAQ,UACR,GAAG,QAC6B;CAChC,MAAM,CAAC,SAAS,cAAc,SAAgC,KAAK;AAEnE,uBAAsB;EACpB;EACA,YAAY;GACV,SAAS;GACT,OAAO;GACR;EACF,CAAC;AAMF,QACE,oBAAC;EAAI,KALkB,aAAa,SAAgC;AACpE,cAAW,KAAK;KACf,EAAE,CAAC;EAGwB,cAAY;EAAO,GAAI;EAChD;GACG;;AAIV,SAAgB,MAAM,OAAsC;CAC1D,MAAM,EAAE,yBAAyB,wBAAwB;CACzD,MAAM,EAAE,aAAa,cAAc;AAEnC,KACE,CAAC,yBAAyB,sBAAsB;EAC9C,SAAS;EACT,OAAO;EACR,CAAC,CAEF,QAAO;AAGT,QAAO,oBAAC,cAAW,GAAI,QAAS"}