@arcote.tech/arc-ds 0.4.1

package/src/layout/overlay-provider.tsx

@@ -0,0 +1,103 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+import { Overlay } from "./overlay";
+import { useArcRoute } from "./router";
+
+export const Z = {
+  BASE: 30,
+  OVERLAY: 40,
+  ELEVATED: 50,
+} as const;
+
+interface OverlayContextValue {
+  requestOverlay: (id: string, onClose: () => void) => void;
+  releaseOverlay: (id: string) => void;
+  isOverlayOwner: (id: string) => boolean;
+  isOverlayVisible: boolean;
+  zIndex: (id: string) => number;
+}
+
+const OverlayContext = createContext<OverlayContextValue | null>(null);
+
+export function OverlayProvider({ children }: { children: ReactNode }) {
+  const [activeId, setActiveId] = useState<string | null>(null);
+  const [exitingId, setExitingId] = useState<string | null>(null);
+  const onCloseRef = useRef<(() => void) | null>(null);
+
+  const requestOverlay = useCallback((id: string, onClose: () => void) => {
+    setActiveId((prev) => {
+      if (prev === id) return prev;
+      return id;
+    });
+    onCloseRef.current = onClose;
+  }, []);
+
+  const releaseOverlay = useCallback((id: string) => {
+    setActiveId((prev) => {
+      if (prev === id) {
+        setExitingId(id);
+        onCloseRef.current = null;
+        return null;
+      }
+      return prev;
+    });
+  }, []);
+
+  const handleOverlayClose = useCallback(() => {
+    const fn = onCloseRef.current;
+    setActiveId((prev) => {
+      if (prev) setExitingId(prev);
+      return null;
+    });
+    onCloseRef.current = null;
+    fn?.();
+  }, []);
+
+  const handleExitComplete = useCallback(() => {
+    setExitingId(null);
+  }, []);
+
+  // Close overlay on route change
+  const path = useArcRoute();
+  useEffect(() => {
+    handleOverlayClose();
+  }, [path]);
+
+  const value = useMemo<OverlayContextValue>(() => {
+    const isOverlayOwner = (id: string) =>
+      activeId === id || (activeId === null && exitingId === id);
+
+    return {
+      requestOverlay,
+      releaseOverlay,
+      isOverlayOwner,
+      isOverlayVisible: activeId !== null,
+      zIndex: (id: string) => (isOverlayOwner(id) ? Z.ELEVATED : Z.BASE),
+    };
+  }, [activeId, exitingId, requestOverlay, releaseOverlay]);
+
+  return (
+    <OverlayContext.Provider value={value}>
+      {children}
+      <Overlay
+        visible={activeId !== null}
+        onClose={handleOverlayClose}
+        onExitComplete={handleExitComplete}
+      />
+    </OverlayContext.Provider>
+  );
+}
+
+export function useOverlay(): OverlayContextValue {
+  const ctx = useContext(OverlayContext);
+  if (!ctx) throw new Error("useOverlay must be used within OverlayProvider");
+  return ctx;
+}

package/src/layout/overlay.tsx

@@ -0,0 +1,33 @@
+import { AnimatePresence, motion } from "framer-motion";
+import { arcTransitions } from "./transitions";
+
+interface OverlayProps {
+  visible: boolean;
+  onClose: () => void;
+  zIndex?: number;
+  onExitComplete?: () => void;
+}
+
+export function Overlay({
+  visible,
+  onClose,
+  zIndex = 40,
+  onExitComplete,
+}: OverlayProps) {
+  return (
+    <AnimatePresence onExitComplete={onExitComplete}>
+      {visible && (
+        <motion.div
+          key="overlay"
+          initial={{ opacity: 0 }}
+          animate={{ opacity: 1 }}
+          exit={{ opacity: 0 }}
+          transition={arcTransitions.fade}
+          className="fixed inset-0 bg-black/20"
+          style={{ zIndex }}
+          onClick={onClose}
+        />
+      )}
+    </AnimatePresence>
+  );
+}

package/src/layout/router.tsx

@@ -0,0 +1,101 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from "react";
+
+interface ArcRouterState {
+  path: string;
+  params: Record<string, string>;
+  navigate: (path: string) => void;
+  back: () => void;
+  setParams: (params: Record<string, string>) => void;
+}
+
+const ArcRouterContext = createContext<ArcRouterState | null>(null);
+
+export function ArcRouterProvider({ children }: { children: ReactNode }) {
+  const [path, setPath] = useState(() => window.location.pathname);
+  const [params, setParams] = useState<Record<string, string>>({});
+
+  const navigate = useCallback((newPath: string) => {
+    window.history.pushState(null, "", newPath);
+    setPath(new URL(newPath, window.location.origin).pathname);
+  }, []);
+
+  const back = useCallback(() => {
+    window.history.back();
+  }, []);
+
+  useEffect(() => {
+    const onPopState = () => setPath(window.location.pathname);
+    window.addEventListener("popstate", onPopState);
+    return () => window.removeEventListener("popstate", onPopState);
+  }, []);
+
+  return (
+    <ArcRouterContext.Provider value={{ path, params, navigate, back, setParams }}>
+      {children}
+    </ArcRouterContext.Provider>
+  );
+}
+
+export function useArcRouter(): ArcRouterState {
+  const ctx = useContext(ArcRouterContext);
+  if (!ctx)
+    throw new Error("useArcRouter must be used within ArcRouterProvider");
+  return ctx;
+}
+
+export function useArcNavigate(): (path: string) => void {
+  return useArcRouter().navigate;
+}
+
+export function useArcRoute(): string {
+  return useArcRouter().path;
+}
+
+export function useArcParams<T extends Record<string, string> = Record<string, string>>(): T {
+  return useArcRouter().params as T;
+}
+
+// --- Route pattern matching utilities ---
+
+/**
+ * Match a URL path against a route pattern with `:param` segments.
+ * Returns extracted params or null if no match.
+ */
+export function matchRoutePath(
+  pattern: string,
+  path: string,
+): Record<string, string> | null {
+  const patternParts = pattern.split("/").filter(Boolean);
+  const pathParts = path.split("/").filter(Boolean);
+
+  // Pattern with params can match paths of same length
+  if (patternParts.length !== pathParts.length) return null;
+
+  const params: Record<string, string> = {};
+
+  for (let i = 0; i < patternParts.length; i++) {
+    const pp = patternParts[i];
+    if (pp.startsWith(":")) {
+      params[pp.slice(1)] = pathParts[i];
+    } else if (pp !== pathParts[i]) {
+      return null;
+    }
+  }
+
+  return params;
+}
+
+/**
+ * Check if a route pattern contains parameter segments (`:param`).
+ */
+export function hasRouteParams(pattern: string): boolean {
+  return pattern.includes("/:");
+}

package/src/layout/scroll-nav.tsx

@@ -0,0 +1,121 @@
+import { Button } from "../ds/button/button";
+import { cn } from "../lib/utils";
+import { motion } from "framer-motion";
+import { ChevronDown } from "lucide-react";
+import {
+  Children,
+  cloneElement,
+  isValidElement,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import { DragHandle } from "./drag-handle";
+import { ExpandablePanel } from "./expandable-panel";
+import { arcTransitions } from "./transitions";
+import { useExpandable } from "./use-expandable";
+
+interface ScrollNavProps {
+  children: ReactNode;
+  className?: string;
+}
+
+export function ScrollNav({ children, className }: ScrollNavProps) {
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const [isOverflowing, setIsOverflowing] = useState(false);
+  const exp = useExpandable();
+
+  useEffect(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+
+    const check = () => setIsOverflowing(el.scrollWidth > el.clientWidth);
+    check();
+
+    const ro = new ResizeObserver(check);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [children]);
+
+  const scrollToCenter = useCallback((element: HTMLElement) => {
+    const container = scrollRef.current;
+    if (!container) return;
+
+    const containerRect = container.getBoundingClientRect();
+    const elementRect = element.getBoundingClientRect();
+
+    const elementCenter = elementRect.left + elementRect.width / 2;
+    const containerCenter = containerRect.left + containerRect.width / 2;
+    const offset = elementCenter - containerCenter;
+
+    container.scrollBy({ left: offset, behavior: "smooth" });
+  }, []);
+
+  const wrappedChildren = Children.map(children, (child) => {
+    if (!isValidElement(child)) return child;
+
+    return cloneElement(child as ReactElement<Record<string, unknown>>, {
+      onClick: (e: React.MouseEvent<HTMLElement>) => {
+        const originalOnClick = (child as ReactElement<Record<string, unknown>>)
+          .props.onClick as
+          | ((e: React.MouseEvent<HTMLElement>) => void)
+          | undefined;
+        originalOnClick?.(e);
+
+        const target = e.currentTarget;
+        requestAnimationFrame(() => scrollToCenter(target));
+      },
+    });
+  });
+
+  return (
+    <div className={cn("relative", className)}>
+      <motion.div
+        animate={
+          exp.isExpanded
+            ? { height: 0, opacity: 0 }
+            : { height: "auto", opacity: 1 }
+        }
+        initial={false}
+        transition={arcTransitions.snappy}
+        style={{ overflow: "hidden" }}
+      >
+        <div className="flex items-center gap-1">
+          <div
+            ref={scrollRef}
+            className="flex flex-1 items-center gap-1 overflow-x-auto scrollbar-none"
+          >
+            {wrappedChildren}
+          </div>
+          {isOverflowing && (
+            <Button
+              icon={ChevronDown}
+              displayMode="minimal"
+              size="icon-xs"
+              onClick={exp.open}
+              className="shrink-0"
+            />
+          )}
+        </div>
+      </motion.div>
+
+      <ExpandablePanel
+        open={exp.isExpanded}
+        height={exp.expandedHeight}
+        dragHeight={exp.dragHeight}
+      >
+        <div ref={exp.expandedRef} className="flex flex-col gap-1">
+          {children}
+          <DragHandle
+            contentHeight={exp.expandedHeight}
+            onHeightChange={exp.onDragHeight}
+            onRelease={exp.onDragRelease}
+          />
+        </div>
+      </ExpandablePanel>
+    </div>
+  );
+}

package/src/layout/slot-render-context.tsx

@@ -0,0 +1,14 @@
+import { createContext, useContext } from "react";
+import type { ReactNode } from "react";
+
+export type SlotRenderFn = (slotId: string, options?: { displayMode?: string; className?: string }) => ReactNode;
+
+const SlotRenderContext = createContext<SlotRenderFn | null>(null);
+
+export const SlotRenderProvider = SlotRenderContext.Provider;
+
+export function useRenderSlot(): SlotRenderFn {
+  const render = useContext(SlotRenderContext);
+  if (!render) return () => null;
+  return render;
+}

package/src/layout/sub-nav-shell.tsx

@@ -0,0 +1,41 @@
+import { Button } from "../ds/button/button";
+import { useMemo } from "react";
+import type { ComponentType, ReactNode } from "react";
+import { useSlotContent } from "./dynamic-slot";
+
+export type SubNavTab = {
+  path: string;
+  icon?: ComponentType<{ className?: string }>;
+  label?: ReactNode;
+  tooltip?: ReactNode;
+  isActive?: boolean;
+};
+
+export type SubNavShellProps = {
+  children: ReactNode;
+  tabs: SubNavTab[];
+  onNavigate: (path: string) => void;
+};
+
+export function SubNavShell({ children, tabs, onNavigate }: SubNavShellProps) {
+  const tabButtons = useMemo(
+    () => (
+      <>
+        {tabs.map((tab) => (
+          <Button
+            key={tab.path}
+            icon={tab.icon}
+            label={tab.label}
+            isActive={tab.isActive}
+            onClick={() => onNavigate(tab.path)}
+          />
+        ))}
+      </>
+    ),
+    [tabs, onNavigate],
+  );
+
+  useSlotContent("sub-nav", "sub-nav-tabs", tabButtons);
+
+  return <div className="px-2">{children}</div>;
+}

package/src/layout/toolbar-expand.tsx

@@ -0,0 +1,70 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useState,
+  type ReactNode,
+} from "react";
+import { useArcRoute } from "./router";
+
+interface ToolbarExpandState {
+  expandedId: string | null;
+  expandedContent: ReactNode | null;
+  expand: (id: string, content: ReactNode) => void;
+  collapse: () => void;
+  toggle: (id: string, content: ReactNode) => void;
+}
+
+const ToolbarExpandContext = createContext<ToolbarExpandState | null>(null);
+
+export function ToolbarExpandProvider({ children }: { children: ReactNode }) {
+  const [expandedId, setExpandedId] = useState<string | null>(null);
+  const [expandedContent, setExpandedContent] = useState<ReactNode | null>(
+    null,
+  );
+
+  const expand = useCallback((id: string, content: ReactNode) => {
+    setExpandedId(id);
+    setExpandedContent(content);
+  }, []);
+
+  const collapse = useCallback(() => {
+    setExpandedId(null);
+    setExpandedContent(null);
+  }, []);
+
+  const toggle = useCallback(
+    (id: string, content: ReactNode) => {
+      if (expandedId === id) {
+        collapse();
+      } else {
+        expand(id, content);
+      }
+    },
+    [expandedId, collapse, expand],
+  );
+
+  // Close expanded toolbar on route change
+  const path = useArcRoute();
+  useEffect(() => {
+    collapse();
+  }, [path]);
+
+  return (
+    <ToolbarExpandContext.Provider
+      value={{ expandedId, expandedContent, expand, collapse, toggle }}
+    >
+      {children}
+    </ToolbarExpandContext.Provider>
+  );
+}
+
+export function useToolbarExpand(): ToolbarExpandState {
+  const ctx = useContext(ToolbarExpandContext);
+  if (!ctx)
+    throw new Error(
+      "useToolbarExpand must be used within ToolbarExpandProvider",
+    );
+  return ctx;
+}

package/src/layout/transitions.ts

@@ -0,0 +1,12 @@
+/**
+ * Arc layout transition presets.
+ * Jedno miejsce do tuningu animacji — wszystkie layout komponenty importują stąd.
+ */
+export const arcTransitions = {
+  /** Szybki spring — expand/collapse paneli, nav overflow. */
+  snappy: { type: "spring" as const, stiffness: 500, damping: 35 },
+  /** Łagodniejszy spring — layout morphing, ArcBox. */
+  smooth: { type: "spring" as const, stiffness: 400, damping: 30 },
+  /** Prosty fade — overlay. */
+  fade: { duration: 0.15 },
+} as const;

package/src/layout/use-expandable.ts

@@ -0,0 +1,59 @@
+import { useCallback, useLayoutEffect, useRef, useState } from "react";
+
+export interface UseExpandableReturn {
+  isExpanded: boolean;
+  open: () => void;
+  close: () => void;
+  toggle: () => void;
+  expandedRef: React.RefObject<HTMLDivElement | null>;
+  expandedHeight: number;
+  dragHeight: number | null;
+  onDragHeight: (height: number) => void;
+  onDragRelease: (shouldClose: boolean) => void;
+  isDragging: boolean;
+}
+
+export function useExpandable(externalOpen?: boolean): UseExpandableReturn {
+  const [internalExpanded, setInternalExpanded] = useState(false);
+  const expandedRef = useRef<HTMLDivElement>(null);
+  const [expandedHeight, setExpandedHeight] = useState(0);
+  const [dragHeight, setDragHeight] = useState<number | null>(null);
+
+  const isExpanded = externalOpen ?? internalExpanded;
+
+  const open = useCallback(() => setInternalExpanded(true), []);
+  const close = useCallback(() => setInternalExpanded(false), []);
+  const toggle = useCallback(() => setInternalExpanded((v) => !v), []);
+
+  useLayoutEffect(() => {
+    const el = expandedRef.current;
+    if (!el) return;
+
+    const measure = () => setExpandedHeight(el.scrollHeight);
+    measure();
+
+    const ro = new ResizeObserver(measure);
+    ro.observe(el);
+    return () => ro.disconnect();
+  });
+
+  const onDragHeight = useCallback((h: number) => setDragHeight(h), []);
+
+  const onDragRelease = useCallback((shouldClose: boolean) => {
+    setDragHeight(null);
+    if (shouldClose) setInternalExpanded(false);
+  }, []);
+
+  return {
+    isExpanded,
+    open,
+    close,
+    toggle,
+    expandedRef,
+    expandedHeight,
+    dragHeight,
+    onDragHeight,
+    onDragRelease,
+    isDragging: dragHeight !== null,
+  };
+}

package/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/src/ui/tooltip.tsx

@@ -0,0 +1,59 @@
+import { Tooltip as TooltipPrimitive } from "radix-ui";
+import * as React from "react";
+import { cn } from "../lib/utils";
+
+function TooltipProvider({
+  delayDuration = 0,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Provider>) {
+  return (
+    <TooltipPrimitive.Provider
+      data-slot="tooltip-provider"
+      delayDuration={delayDuration}
+      {...props}
+    />
+  );
+}
+
+function TooltipRoot({
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Root>) {
+  return <TooltipPrimitive.Root data-slot="tooltip" {...props} />;
+}
+
+function TooltipTrigger({
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
+  return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />;
+}
+
+function TooltipContent({
+  className,
+  sideOffset = 0,
+  children,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Content>) {
+  return (
+    <TooltipPrimitive.Portal>
+      <TooltipPrimitive.Content
+        data-slot="tooltip-content"
+        sideOffset={sideOffset}
+        className={cn(
+          "z-50 w-fit origin-(--radix-tooltip-content-transform-origin) animate-in rounded-md bg-foreground px-3 py-1.5 text-xs text-balance text-background fade-in-0 zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95",
+          className,
+        )}
+        {...props}
+      >
+        {children}
+        <TooltipPrimitive.Arrow className="z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px] bg-foreground fill-foreground" />
+      </TooltipPrimitive.Content>
+    </TooltipPrimitive.Portal>
+  );
+}
+
+export {
+  TooltipRoot as Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+};

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx"],
+  "exclude": ["node_modules", "dist"]
+}