@arcote.tech/arc-ds 0.4.1

package/src/index.ts

@@ -0,0 +1,115 @@
+// Design System — public API
+
+// Provider
+export {
+  DesignSystemProvider,
+  useDsComponent,
+  useDsVariantOverrides,
+} from "./ds/ds-provider";
+
+// Display Mode
+export { DisplayModeProvider, useDisplayMode } from "./ds/display-mode";
+
+// Transitions
+export { dsTransitions } from "./ds/transitions";
+
+// Form
+export {
+  Form,
+  FormContext,
+  FormField,
+  FormMessage,
+  FormPart,
+  useForm,
+  useFormField,
+  useFormPart,
+  TextField,
+  TextareaField,
+  TagField,
+  SelectField,
+  SuggestionListField,
+  SearchSelectField,
+  CheckboxSelectField,
+} from "./ds/form";
+export type {
+  FormProps,
+  FormRef,
+  FormFields,
+  FormFieldData,
+  TextFieldProps,
+  TextareaFieldProps,
+  TagFieldProps,
+  SelectFieldProps,
+  SuggestionListFieldProps,
+  SearchSelectFieldProps,
+  CheckboxSelectFieldProps,
+  CheckboxSelectOption,
+} from "./ds/form";
+
+// Components
+export {
+  Avatar,
+  avatarFallbackVariants,
+  avatarVariants,
+} from "./ds/avatar/avatar";
+export { BentoCard } from "./ds/bento-card/bento-card";
+export type { BentoCardProps } from "./ds/bento-card/bento-card";
+export { BentoGrid, useBentoSpan } from "./ds/bento-grid/bento-grid";
+export type { BentoGridProps } from "./ds/bento-grid/bento-grid";
+export { CardModal, CardFormModal, ModalActions } from "./ds/card-modal/card-modal";
+export type { CardModalProps, CardFormModalProps, ModalActionsProps } from "./ds/card-modal/card-modal";
+export { TagList } from "./ds/tag-list/tag-list";
+export type { TagListProps } from "./ds/tag-list/tag-list";
+export { SuggestionList } from "./ds/suggestion-list/suggestion-list";
+export type { SuggestionListProps, InitialCloudConfig } from "./ds/suggestion-list/suggestion-list";
+export { SearchSelect } from "./ds/search-select/search-select";
+export type { SearchSelectProps, SearchSelectOption } from "./ds/search-select/search-select";
+export { Badge, badgeVariants } from "./ds/badge/badge";
+export { Box, boxVariants } from "./ds/box/box";
+export type { BoxProps } from "./ds/box/box";
+export {
+  Button,
+  buttonIconVariants,
+  buttonLabelVariants,
+  buttonVariants,
+} from "./ds/button/button";
+export { Input, inputIconVariants, inputVariants } from "./ds/input/input";
+export { Separator } from "./ds/separator/separator";
+export { Tooltip } from "./ds/tooltip/tooltip";
+export { TooltipProvider } from "./ui/tooltip";
+
+// Utilities
+export { mergeVariants } from "./ds/merge-variants";
+export { cn } from "./lib/utils";
+
+// Layout
+export { Layout } from "./layout/layout";
+export { DynamicSlotProvider, useSlotContent, useDynamicSlotContent } from "./layout/dynamic-slot";
+export { OverlayProvider, useOverlay, Z } from "./layout/overlay-provider";
+export { ScrollNav } from "./layout/scroll-nav";
+export { SlotRenderProvider, useRenderSlot } from "./layout/slot-render-context";
+export type { SlotRenderFn } from "./layout/slot-render-context";
+export { SubNavShell } from "./layout/sub-nav-shell";
+export type { SubNavShellProps, SubNavTab } from "./layout/sub-nav-shell";
+export { ArcRouterProvider, useArcRouter, useArcNavigate, useArcRoute, useArcParams, matchRoutePath, hasRouteParams } from "./layout/router";
+export { ToolbarExpandProvider, useToolbarExpand } from "./layout/toolbar-expand";
+export { arcTransitions } from "./layout/transitions";
+export { DragHandle } from "./layout/drag-handle";
+export { ExpandablePanel } from "./layout/expandable-panel";
+export { useExpandable } from "./layout/use-expandable";
+export type { UseExpandableReturn } from "./layout/use-expandable";
+
+// Types
+export type {
+  AvatarProps,
+  BadgeProps,
+  ButtonProps,
+  CVAVariantOverride,
+  DSComponentMap,
+  DSComponentOverrides,
+  DSVariantOverrides,
+  DisplayMode,
+  InputProps,
+  SeparatorProps,
+  TooltipProps,
+} from "./ds/types";

package/src/layout/drag-handle.tsx

@@ -0,0 +1,117 @@
+import { useCallback, useEffect, useRef } from "react";
+
+interface DragHandleProps {
+  contentHeight: number;
+  onHeightChange: (height: number) => void;
+  onRelease: (shouldClose: boolean) => void;
+  closeThreshold?: number;
+  closeDirection?: "up" | "down";
+  className?: string;
+}
+
+export function DragHandle({
+  contentHeight,
+  onHeightChange,
+  onRelease,
+  closeThreshold = 0.4,
+  closeDirection = "up",
+  className,
+}: DragHandleProps) {
+  const elRef = useRef<HTMLButtonElement>(null);
+  const startYRef = useRef(0);
+  const startHeightRef = useRef(0);
+  const isDraggingRef = useRef(false);
+
+  const sign = closeDirection === "up" ? 1 : -1;
+
+  const handleStart = useCallback(
+    (clientY: number) => {
+      startYRef.current = clientY;
+      startHeightRef.current = contentHeight;
+      isDraggingRef.current = true;
+    },
+    [contentHeight],
+  );
+
+  const handleMove = useCallback(
+    (clientY: number) => {
+      if (!isDraggingRef.current) return;
+      const delta = clientY - startYRef.current;
+      const newHeight = Math.max(
+        0,
+        Math.min(startHeightRef.current, startHeightRef.current + delta * sign),
+      );
+      onHeightChange(newHeight);
+    },
+    [onHeightChange, sign],
+  );
+
+  const handleEnd = useCallback(
+    (clientY: number) => {
+      if (!isDraggingRef.current) return;
+      isDraggingRef.current = false;
+      const delta = clientY - startYRef.current;
+      const ratio = (-delta * sign) / startHeightRef.current;
+      onRelease(ratio > closeThreshold);
+    },
+    [onRelease, closeThreshold, sign],
+  );
+
+  useEffect(() => {
+    const el = elRef.current;
+    if (!el) return;
+
+    const onTouchStart = (e: TouchEvent) => handleStart(e.touches[0].clientY);
+    const onTouchMove = (e: TouchEvent) => {
+      e.preventDefault();
+      handleMove(e.touches[0].clientY);
+    };
+    const onTouchEnd = (e: TouchEvent) =>
+      handleEnd(e.changedTouches[0].clientY);
+
+    el.addEventListener("touchstart", onTouchStart, { passive: true });
+    el.addEventListener("touchmove", onTouchMove, { passive: false });
+    el.addEventListener("touchend", onTouchEnd, { passive: true });
+
+    return () => {
+      el.removeEventListener("touchstart", onTouchStart);
+      el.removeEventListener("touchmove", onTouchMove);
+      el.removeEventListener("touchend", onTouchEnd);
+    };
+  }, [handleStart, handleMove, handleEnd]);
+
+  const onMouseDown = useCallback(
+    (e: React.MouseEvent) => {
+      e.preventDefault();
+      handleStart(e.clientY);
+
+      const onMouseMove = (ev: MouseEvent) => handleMove(ev.clientY);
+      const onMouseUp = (ev: MouseEvent) => {
+        handleEnd(ev.clientY);
+        window.removeEventListener("mousemove", onMouseMove);
+        window.removeEventListener("mouseup", onMouseUp);
+      };
+
+      window.addEventListener("mousemove", onMouseMove);
+      window.addEventListener("mouseup", onMouseUp);
+    },
+    [handleStart, handleMove, handleEnd],
+  );
+
+  return (
+    <button
+      ref={elRef}
+      onMouseDown={onMouseDown}
+      onClick={(e) => {
+        if (!isDraggingRef.current) onRelease(true);
+        e.preventDefault();
+      }}
+      className={
+        className ?? "flex w-full items-center justify-center py-3 touch-none"
+      }
+      aria-label="Close"
+    >
+      <div className="h-1 w-8 rounded-full bg-muted-foreground/40 transition-colors hover:bg-muted-foreground/60" />
+    </button>
+  );
+}

package/src/layout/dynamic-slot.tsx

@@ -0,0 +1,95 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import type { ReactNode } from "react";
+
+type DynamicSlotEntry = {
+  id: string;
+  content: ReactNode;
+};
+
+type DynamicSlotContextValue = {
+  entries: Map<string, DynamicSlotEntry[]>;
+  register: (slotId: string, id: string, content: ReactNode) => void;
+  unregister: (slotId: string, id: string) => void;
+};
+
+const DynamicSlotContext = createContext<DynamicSlotContextValue | null>(null);
+
+export function DynamicSlotProvider({ children }: { children: ReactNode }) {
+  const [entries, setEntries] = useState<Map<string, DynamicSlotEntry[]>>(
+    () => new Map(),
+  );
+
+  const register = useCallback(
+    (slotId: string, id: string, content: ReactNode) => {
+      setEntries((prev) => {
+        const next = new Map(prev);
+        const slot = next.get(slotId) ?? [];
+        const existing = slot.findIndex((e) => e.id === id);
+        if (existing >= 0) {
+          slot[existing] = { id, content };
+        } else {
+          slot.push({ id, content });
+        }
+        next.set(slotId, [...slot]);
+        return next;
+      });
+    },
+    [],
+  );
+
+  const unregister = useCallback((slotId: string, id: string) => {
+    setEntries((prev) => {
+      const next = new Map(prev);
+      const slot = next.get(slotId);
+      if (slot) {
+        const filtered = slot.filter((e) => e.id !== id);
+        if (filtered.length > 0) {
+          next.set(slotId, filtered);
+        } else {
+          next.delete(slotId);
+        }
+      }
+      return next;
+    });
+  }, []);
+
+  const value = useMemo(
+    () => ({ entries, register, unregister }),
+    [entries, register, unregister],
+  );
+
+  return (
+    <DynamicSlotContext.Provider value={value}>
+      {children}
+    </DynamicSlotContext.Provider>
+  );
+}
+
+/**
+ * Register dynamic content into a named slot.
+ * Content appears while the component is mounted, removed on unmount.
+ */
+export function useSlotContent(slotId: string, id: string, content: ReactNode) {
+  const ctx = useContext(DynamicSlotContext);
+  if (!ctx) throw new Error("useSlotContent requires DynamicSlotProvider");
+
+  const registerRef = useRef(ctx.register);
+  const unregisterRef = useRef(ctx.unregister);
+  registerRef.current = ctx.register;
+  unregisterRef.current = ctx.unregister;
+
+  useEffect(() => {
+    registerRef.current(slotId, id, content);
+    return () => unregisterRef.current(slotId, id);
+  }, [slotId, id, content]);
+}
+
+/**
+ * Read dynamic slot content for a given slot ID.
+ */
+export function useDynamicSlotContent(slotId: string): ReactNode[] {
+  const ctx = useContext(DynamicSlotContext);
+  if (!ctx) return [];
+  const entries = ctx.entries.get(slotId);
+  return entries ? entries.map((e) => e.content) : [];
+}

package/src/layout/expandable-panel.tsx

@@ -0,0 +1,57 @@
+import { motion } from "framer-motion";
+import { useLayoutEffect, useRef, useState, type ReactNode } from "react";
+import { arcTransitions } from "./transitions";
+
+interface ExpandablePanelProps {
+  open: boolean;
+  height?: number;
+  dragHeight?: number | null;
+  children: ReactNode;
+}
+
+export function ExpandablePanel({
+  open,
+  height: externalHeight,
+  dragHeight = null,
+  children,
+}: ExpandablePanelProps) {
+  const innerRef = useRef<HTMLDivElement>(null);
+  const [measuredHeight, setMeasuredHeight] = useState(0);
+
+  useLayoutEffect(() => {
+    const el = innerRef.current;
+    if (!el) return;
+
+    const measure = () => setMeasuredHeight(el.offsetHeight);
+    measure();
+
+    const ro = new ResizeObserver(measure);
+    ro.observe(el);
+    return () => ro.disconnect();
+  });
+
+  const targetHeight = externalHeight ?? measuredHeight;
+  const isDragging = dragHeight !== null;
+
+  return (
+    <motion.div
+      data-expanded={open || undefined}
+      animate={
+        isDragging
+          ? undefined
+          : { height: open ? targetHeight : 0, opacity: open ? 1 : 0 }
+      }
+      style={
+        isDragging
+          ? { height: dragHeight, opacity: 1, overflow: "hidden" }
+          : { overflow: "hidden" }
+      }
+      initial={false}
+      transition={arcTransitions.snappy}
+    >
+      <div ref={innerRef} className="flex flex-col">
+        {children}
+      </div>
+    </motion.div>
+  );
+}

package/src/layout/layout.tsx

@@ -0,0 +1,323 @@
+import { createContext, useContext, useEffect, useRef, useState } from "react";
+import type { ReactNode } from "react";
+import { Box } from "../ds/box/box";
+import { Button } from "../ds/button/button";
+import { DragHandle } from "./drag-handle";
+import { useDynamicSlotContent } from "./dynamic-slot";
+import { ExpandablePanel } from "./expandable-panel";
+import { useOverlay } from "./overlay-provider";
+import { useRenderSlot } from "./slot-render-context";
+import { ToolbarExpandProvider, useToolbarExpand } from "./toolbar-expand";
+import { useExpandable } from "./use-expandable";
+import { ChevronDown } from "lucide-react";
+
+function useMediaQuery(query: string): boolean {
+  const [matches, setMatches] = useState(
+    () => window.matchMedia(query).matches,
+  );
+
+  useEffect(() => {
+    const mq = window.matchMedia(query);
+    const handler = (e: MediaQueryListEvent) => setMatches(e.matches);
+    mq.addEventListener("change", handler);
+    return () => mq.removeEventListener("change", handler);
+  }, [query]);
+
+  return matches;
+}
+
+export function Layout({ children }: { children?: ReactNode }) {
+  const isDesktop = useMediaQuery("(min-width: 768px)");
+
+  return (
+    <ToolbarExpandProvider>
+      {isDesktop ? (
+        <DesktopLayout>{children}</DesktopLayout>
+      ) : (
+        <MobileLayout>{children}</MobileLayout>
+      )}
+    </ToolbarExpandProvider>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Desktop
+// ---------------------------------------------------------------------------
+
+function SubNavSlot() {
+  const content = useDynamicSlotContent("sub-nav");
+  if (content.length === 0) return null;
+  return (
+    <div className="flex justify-center py-2">
+      <Box layoutId="sub-nav" className="flex items-center gap-1 px-3 py-2">
+        {content}
+      </Box>
+    </div>
+  );
+}
+
+function DesktopLayout({ children }: { children?: ReactNode }) {
+  const renderSlot = useRenderSlot();
+
+  return (
+    <>
+      <DesktopToolbar />
+      <div className="h-16" />
+      <SubNavSlot />
+      <div className="mx-auto flex w-full max-w-5xl flex-1 gap-4 p-4">
+        {renderSlot("sidebar-left", { className: "flex w-64 shrink-0 flex-col gap-4" })}
+        <div className="min-w-0 flex-1">
+          {children}
+          {renderSlot("main-content", { className: "flex flex-col gap-4" })}
+        </div>
+        {renderSlot("sidebar-right", { className: "flex w-64 shrink-0 flex-col gap-4" })}
+      </div>
+    </>
+  );
+}
+
+function DesktopToolbar() {
+  const renderSlot = useRenderSlot();
+  const { expandedId, collapse } = useToolbarExpand();
+  const { requestOverlay, releaseOverlay, zIndex } = useOverlay();
+  const prevIdRef = useRef<string | null>(null);
+  const collapseRef = useRef(collapse);
+  collapseRef.current = collapse;
+
+  useEffect(() => {
+    const prevId = prevIdRef.current;
+    prevIdRef.current = expandedId;
+
+    if (expandedId) {
+      requestOverlay(expandedId, () => collapseRef.current());
+    } else if (prevId) {
+      releaseOverlay(prevId);
+    }
+  }, [expandedId, requestOverlay, releaseOverlay]);
+
+  return (
+    <>
+      <div
+        className="fixed left-4 top-4"
+        style={{ zIndex: zIndex("workspace") }}
+      >
+        <Box layout={false} className="flex flex-col px-3 py-2">
+          {renderSlot("toolbar-left", { className: "flex items-center gap-2" })}
+          <ExpandedSection targetId="workspace" />
+        </Box>
+      </div>
+
+      <div
+        className="fixed left-1/2 top-4 max-w-[calc(100vw-26rem)] -translate-x-1/2"
+        style={{ zIndex: zIndex("center") }}
+      >
+        <Box layout={false} className="flex min-w-0 items-center px-3 py-2">
+          {renderSlot("toolbar-center", { className: "flex min-w-0 flex-1 items-center gap-1" })}
+        </Box>
+      </div>
+
+      <div
+        className="fixed right-4 top-4"
+        style={{ zIndex: zIndex("settings") }}
+      >
+        <Box layout={false} className="flex flex-col px-3 py-2">
+          {renderSlot("toolbar-right", { className: "flex items-center gap-2" })}
+          <ExpandedSection targetId="settings" />
+        </Box>
+      </div>
+    </>
+  );
+}
+
+function ExpandedSection({ targetId }: { targetId: string }) {
+  const { expandedId, expandedContent } = useToolbarExpand();
+  const isActive = expandedId === targetId;
+
+  return (
+    <ExpandablePanel open={isActive}>
+      <div className="mt-2 border-t pt-2">{isActive && expandedContent}</div>
+    </ExpandablePanel>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Mobile
+// ---------------------------------------------------------------------------
+
+function MobileSubNavSlot() {
+  const content = useDynamicSlotContent("sub-nav");
+  const { expand, expandedId, collapse } = useToolbarExpand();
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const [isOverflowing, setIsOverflowing] = useState(false);
+
+  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();
+  }, [content]);
+
+  // Auto-scroll to active tab on content change (route change)
+  useEffect(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    const active = el.querySelector("[data-active='true']") as HTMLElement | null;
+    if (!active) return;
+    const containerRect = el.getBoundingClientRect();
+    const activeRect = active.getBoundingClientRect();
+    const offset = activeRect.left + activeRect.width / 2 - containerRect.left - containerRect.width / 2;
+    el.scrollBy({ left: offset, behavior: "smooth" });
+  }, [content]);
+
+  if (content.length === 0) return null;
+  if (expandedId) return null;
+  return (
+    <div className="mt-2 border-t pt-2">
+      <div className="flex items-center gap-1">
+        <div
+          ref={scrollRef}
+          className="flex flex-1 items-center gap-1 overflow-x-auto scrollbar-none"
+        >
+          {content}
+        </div>
+        {isOverflowing && (
+          <Button
+            icon={ChevronDown}
+            displayMode="minimal"
+            size="icon-xs"
+            onClick={() => expand("sub-nav",
+              <div className="flex flex-col gap-1" onClick={() => collapse()}>
+                {content}
+              </div>
+            )}
+            className="shrink-0"
+          />
+        )}
+      </div>
+    </div>
+  );
+}
+
+const MobileSpacingContext = createContext<{
+  setTopHeight: (h: number) => void;
+  setBottomHeight: (h: number) => void;
+}>({ setTopHeight: () => {}, setBottomHeight: () => {} });
+
+function MobileLayout({ children }: { children?: ReactNode }) {
+  const renderSlot = useRenderSlot();
+  const [topHeight, setTopHeight] = useState(64);
+  const [bottomHeight, setBottomHeight] = useState(64);
+  const gap = 8;
+
+  return (
+    <MobileSpacingContext.Provider value={{ setTopHeight, setBottomHeight }}>
+      <MobileToolbar />
+      <div style={{ height: topHeight + gap }} />
+      <div className="mx-auto w-full max-w-lg flex-1 p-2" style={{ paddingBottom: bottomHeight + gap }}>
+        {children}
+        {renderSlot("main-content", { className: "flex flex-col gap-2" })}
+      </div>
+      <MobileBottomBar />
+    </MobileSpacingContext.Provider>
+  );
+}
+
+function MobileToolbar() {
+  const renderSlot = useRenderSlot();
+  const { expandedId, expandedContent, collapse } = useToolbarExpand();
+  const isExpanded = expandedId !== null;
+  const exp = useExpandable(isExpanded);
+  const { requestOverlay, releaseOverlay, zIndex } = useOverlay();
+  const { setTopHeight } = useContext(MobileSpacingContext);
+  const toolbarRef = useRef<HTMLDivElement>(null);
+  const collapseRef = useRef(collapse);
+  collapseRef.current = collapse;
+
+  useEffect(() => {
+    if (isExpanded) {
+      requestOverlay("mobile-toolbar", () => collapseRef.current());
+    } else {
+      releaseOverlay("mobile-toolbar");
+    }
+  }, [isExpanded, requestOverlay, releaseOverlay]);
+
+  useEffect(() => {
+    const el = toolbarRef.current;
+    if (!el) return;
+    const update = () => setTopHeight(el.offsetHeight);
+    update();
+    const ro = new ResizeObserver(update);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [setTopHeight]);
+
+  return (
+    <div
+      ref={toolbarRef}
+      className="fixed inset-x-0 top-0 p-2"
+      style={{ zIndex: zIndex("mobile-toolbar") }}
+    >
+      <Box layoutId="mobile-toolbar" className="px-3 py-2">
+        <div className="flex items-center justify-between">
+          {renderSlot("toolbar-left", { displayMode: "minimal", className: "flex items-center gap-2" })}
+          {renderSlot("toolbar-right", { displayMode: "minimal", className: "flex items-center gap-1" })}
+        </div>
+
+        <MobileSubNavSlot />
+
+        <ExpandablePanel
+          open={isExpanded}
+          height={exp.expandedHeight}
+          dragHeight={exp.dragHeight}
+        >
+          <div ref={exp.expandedRef} className="flex flex-col">
+            <div className="mt-2 border-t pt-3">{expandedContent}</div>
+            <DragHandle
+              contentHeight={exp.expandedHeight}
+              onHeightChange={exp.onDragHeight}
+              onRelease={(shouldClose) => {
+                exp.onDragRelease(shouldClose);
+                if (shouldClose) collapse();
+              }}
+            />
+          </div>
+        </ExpandablePanel>
+      </Box>
+    </div>
+  );
+}
+
+function MobileBottomBar() {
+  const renderSlot = useRenderSlot();
+  const { zIndex } = useOverlay();
+  const { setBottomHeight } = useContext(MobileSpacingContext);
+  const barRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const el = barRef.current;
+    if (!el) return;
+    const update = () => setBottomHeight(el.offsetHeight);
+    update();
+    const ro = new ResizeObserver(update);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [setBottomHeight]);
+
+  return (
+    <div
+      ref={barRef}
+      className="fixed inset-x-0 bottom-0 p-2"
+      style={{ zIndex: zIndex("overflow-nav") }}
+    >
+      <Box
+        layoutId="mobile-bottom-bar"
+        className="border-t px-2 py-2 shadow-lg"
+      >
+        {renderSlot("toolbar-center", { displayMode: "compact", className: "flex items-center justify-around" })}
+      </Box>
+    </div>
+  );
+}