gladvn 0.2.14

package/src/components/micro/select.tsx

@@ -0,0 +1,234 @@
+/**
+ * ✅ AUDITED & REFACTORED
+ * - Design System Compliant (22 Commandments)
+ * - WCAG AAA/AA
+ * - Form Control Parity
+ * - CSS Delegated Logic
+ */
+"use client";
+
+import { Select as SelectPrimitive } from "@base-ui/react/select";
+import { cva, type VariantProps } from "class-variance-authority";
+import * as React from "react";
+
+import { cn } from "../../lib/utils";
+import { CheckIcon, ChevronDownIcon, ChevronUpIcon } from "lucide-react";
+
+const Select = SelectPrimitive.Root;
+
+const SelectGroup = React.forwardRef<
+  React.ComponentRef<typeof SelectPrimitive.Group>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Group>
+>(({ className, ...props }, ref) => (
+  <SelectPrimitive.Group
+    ref={ref}
+    data-slot="select-group"
+    className={cn("scroll-my-1", className)}
+    {...props}
+  />
+));
+SelectGroup.displayName = "SelectGroup";
+
+const SelectValue = React.forwardRef<
+  React.ComponentRef<typeof SelectPrimitive.Value>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Value>
+>(({ className, ...props }, ref) => (
+  <SelectPrimitive.Value
+    ref={ref}
+    data-slot="select-value"
+    className={cn("flex flex-1 text-left", className)}
+    {...props}
+  />
+));
+SelectValue.displayName = "SelectValue";
+
+const SelectPortal = SelectPrimitive.Portal;
+
+const selectTriggerVariants = cva(
+  "inline-flex items-center justify-between rounded-lg border border-input bg-transparent text-foreground text-sm whitespace-nowrap transition-colors outline-none select-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 focus-visible:ring-offset-1 focus-visible:ring-offset-background disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:focus-visible:ring-3 aria-invalid:focus-visible:ring-destructive/50 data-placeholder:text-muted-foreground [&_[data-slot=select-value]]:line-clamp-1 [&_[data-slot=select-value]]:flex [&_[data-slot=select-value]]:items-center [&>svg]:pointer-events-none [&>svg]:shrink-0 [&>svg:not([class*='size-'])]:size-4 dark:bg-input/30 dark:aria-invalid:border-destructive/50 dark:aria-invalid:focus-visible:ring-destructive/50",
+  {
+    variants: {
+      size: {
+        sm: "h-7 gap-1 px-2 py-0.5 text-xs [&_[data-slot=select-value]]:gap-1",
+        md: "h-8 gap-1.5 px-2.5 py-1 text-sm [&_[data-slot=select-value]]:gap-1.5",
+        lg: "h-9 gap-2 px-3 py-1.5 [&_[data-slot=select-value]]:gap-2",
+      },
+    },
+  },
+);
+
+const SelectTrigger = React.forwardRef<
+  React.ComponentRef<typeof SelectPrimitive.Trigger>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Trigger> &
+    VariantProps<typeof selectTriggerVariants>
+>(({ className, size = "md", children, ...props }, ref) => (
+  <SelectPrimitive.Trigger
+    ref={ref}
+    data-slot="select-trigger"
+    className={cn(selectTriggerVariants({ size, className }))}
+    {...props}
+  >
+    {children}
+    <SelectPrimitive.Icon
+      render={
+        <ChevronDownIcon className="pointer-events-none size-4 text-muted-foreground" />
+      }
+    />
+  </SelectPrimitive.Trigger>
+));
+SelectTrigger.displayName = "SelectTrigger";
+
+const SelectContent = React.forwardRef<
+  React.ComponentRef<typeof SelectPrimitive.Popup>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Popup> &
+    Pick<
+      SelectPrimitive.Positioner.Props,
+      "align" | "alignOffset" | "side" | "sideOffset" | "alignItemWithTrigger"
+    >
+>(
+  (
+    {
+      className,
+      children,
+      side = "bottom",
+      sideOffset = 4,
+      align = "center",
+      alignOffset = 0,
+      alignItemWithTrigger = false,
+      ...props
+    },
+    ref,
+  ) => (
+    <SelectPrimitive.Positioner
+      side={side}
+      sideOffset={sideOffset}
+      align={align}
+      alignOffset={alignOffset}
+      alignItemWithTrigger={alignItemWithTrigger}
+      className="isolate z-50"
+    >
+      <SelectPrimitive.Popup
+        ref={ref}
+        data-slot="select-content"
+        data-align-trigger={alignItemWithTrigger}
+        className={cn(
+          "relative isolate z-50 max-h-(--available-height) w-[calc(var(--anchor-width)+8px)] overflow-x-hidden overflow-y-auto rounded-lg bg-popover p-1 text-popover-foreground shadow-md ring-1 ring-foreground/10 data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-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-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+          alignItemWithTrigger
+            ? "origin-(--transform-origin) data-[align-trigger=true]:animate-none"
+            : "",
+          className,
+        )}
+        {...props}
+      >
+        <SelectScrollUpButton />
+        <SelectPrimitive.List>{children}</SelectPrimitive.List>
+        <SelectScrollDownButton />
+      </SelectPrimitive.Popup>
+    </SelectPrimitive.Positioner>
+  ),
+);
+SelectContent.displayName = "SelectContent";
+
+const SelectLabel = React.forwardRef<
+  React.ComponentRef<typeof SelectPrimitive.GroupLabel>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.GroupLabel>
+>(({ className, ...props }, ref) => (
+  <SelectPrimitive.GroupLabel
+    ref={ref}
+    data-slot="select-label"
+    className={cn("px-1.5 py-1 text-xs text-muted-foreground", className)}
+    {...props}
+  />
+));
+SelectLabel.displayName = "SelectLabel";
+
+const SelectItem = React.forwardRef<
+  React.ComponentRef<typeof SelectPrimitive.Item>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Item>
+>(({ className, children, ...props }, ref) => (
+  <SelectPrimitive.Item
+    ref={ref}
+    data-slot="select-item"
+    className={cn(
+      "relative flex w-full cursor-default items-center gap-1.5 rounded-md py-1 pr-8 pl-1.5 text-sm outline-hidden select-none data-highlighted:bg-accent data-highlighted:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-50 [&>svg]:pointer-events-none [&>svg]:shrink-0 [&>svg:not([class*='size-'])]:size-4 [&>[data-slot=select-item-indicator]]:flex [&>[data-slot=select-item-indicator]]:items-center [&>[data-slot=select-item-indicator]]:gap-2",
+      className,
+    )}
+    {...props}
+  >
+    <SelectPrimitive.ItemText className="flex flex-1 shrink-0 gap-2 whitespace-nowrap">
+      {children}
+    </SelectPrimitive.ItemText>
+    <SelectPrimitive.ItemIndicator
+      render={
+        <span className="pointer-events-none absolute right-2 flex size-4 items-center justify-center" />
+      }
+    >
+      <CheckIcon className="pointer-events-none" />
+    </SelectPrimitive.ItemIndicator>
+  </SelectPrimitive.Item>
+));
+SelectItem.displayName = "SelectItem";
+
+const SelectSeparator = React.forwardRef<
+  React.ComponentRef<typeof SelectPrimitive.Separator>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Separator>
+>(({ className, ...props }, ref) => (
+  <SelectPrimitive.Separator
+    ref={ref}
+    data-slot="select-separator"
+    className={cn("pointer-events-none -mx-1 my-1 h-px bg-border", className)}
+    {...props}
+  />
+));
+SelectSeparator.displayName = "SelectSeparator";
+
+const SelectScrollUpButton = React.forwardRef<
+  React.ComponentRef<typeof SelectPrimitive.ScrollUpArrow>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.ScrollUpArrow>
+>(({ className, ...props }, ref) => (
+  <SelectPrimitive.ScrollUpArrow
+    ref={ref}
+    data-slot="select-scroll-up-button"
+    className={cn(
+      "top-0 z-10 flex cursor-default items-center justify-center bg-popover py-1 [&_svg:not([class*='size-'])]:size-4",
+      className,
+    )}
+    {...props}
+  >
+    <ChevronUpIcon />
+  </SelectPrimitive.ScrollUpArrow>
+));
+SelectScrollUpButton.displayName = "SelectScrollUpButton";
+
+const SelectScrollDownButton = React.forwardRef<
+  React.ComponentRef<typeof SelectPrimitive.ScrollDownArrow>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.ScrollDownArrow>
+>(({ className, ...props }, ref) => (
+  <SelectPrimitive.ScrollDownArrow
+    ref={ref}
+    data-slot="select-scroll-down-button"
+    className={cn(
+      "bottom-0 z-10 flex cursor-default items-center justify-center bg-popover py-1 [&_svg:not([class*='size-'])]:size-4",
+      className,
+    )}
+    {...props}
+  >
+    <ChevronDownIcon />
+  </SelectPrimitive.ScrollDownArrow>
+));
+SelectScrollDownButton.displayName = "SelectScrollDownButton";
+
+export {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectPortal,
+  SelectScrollDownButton,
+  SelectScrollUpButton,
+  SelectSeparator,
+  SelectTrigger,
+  selectTriggerVariants,
+  SelectValue,
+};

package/src/components/micro/separator.tsx

@@ -0,0 +1,37 @@
+/**
+ * ✅ AUDITED & REFACTORED
+ * - Design System Compliant (22 Commandments)
+ * - WCAG AAA/AA
+ * - Form Control Parity
+ * - CSS Delegated Logic
+ */
+"use client";
+
+import { Separator as SeparatorPrimitive } from "@base-ui/react/separator";
+
+import { cn } from "../../lib/utils";
+
+/**
+ * @description Visually or semantically separates content.
+ * @example
+ * <Separator orientation="vertical" />
+ */
+function Separator({
+  className,
+  orientation = "horizontal",
+  ...props
+}: SeparatorPrimitive.Props) {
+  return (
+    <SeparatorPrimitive
+      data-slot="separator"
+      orientation={orientation}
+      className={cn(
+        "shrink-0 bg-border data-horizontal:h-px data-horizontal:w-full data-vertical:w-px data-vertical:self-stretch",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export { Separator };

package/src/components/micro/sheet.tsx

@@ -0,0 +1,144 @@
+/**
+ * ✅ AUDITED & REFACTORED
+ * - Design System Compliant (22 Commandments)
+ * - WCAG AAA/AA
+ * - Form Control Parity
+ * - CSS Delegated Logic
+ */
+"use client";
+
+import { Dialog as SheetPrimitive } from "@base-ui/react/dialog";
+import * as React from "react";
+import { XIcon } from "lucide-react";
+
+import { Button } from "../../components/micro/button";
+import { cn } from "../../lib/utils";
+
+function Sheet({ ...props }: SheetPrimitive.Root.Props) {
+  return <SheetPrimitive.Root data-slot="sheet" {...props} />;
+}
+
+function SheetTrigger({ ...props }: SheetPrimitive.Trigger.Props) {
+  return <SheetPrimitive.Trigger data-slot="sheet-trigger" {...props} />;
+}
+
+function SheetClose({ ...props }: SheetPrimitive.Close.Props) {
+  return <SheetPrimitive.Close data-slot="sheet-close" {...props} />;
+}
+
+const SheetPortal = SheetPrimitive.Portal;
+
+function SheetOverlay({ className, ...props }: SheetPrimitive.Backdrop.Props) {
+  return (
+    <SheetPrimitive.Backdrop
+      data-slot="sheet-overlay"
+      className={cn(
+        "fixed inset-0 z-50 bg-black/10 transition-opacity duration-150 data-ending-style:opacity-0 data-starting-style:opacity-0 supports-backdrop-filter:backdrop-blur-xs motion-reduce:transition-none",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function SheetContent({
+  className,
+  children,
+  side = "right",
+  showCloseButton = true,
+  ...props
+}: SheetPrimitive.Popup.Props & {
+  side?: "top" | "right" | "bottom" | "left";
+  showCloseButton?: boolean;
+}) {
+  return (
+    <>
+      <SheetOverlay />
+      <SheetPrimitive.Popup
+        data-slot="sheet-content"
+        data-side={side}
+        className={cn(
+          "fixed z-50 flex flex-col gap-4 bg-popover bg-clip-padding text-sm text-popover-foreground shadow-lg transition duration-200 ease-in-out data-ending-style:opacity-0 data-starting-style:opacity-0 data-[side=bottom]:inset-x-0 data-[side=bottom]:bottom-0 data-[side=bottom]:h-auto data-[side=bottom]:border-t data-[side=bottom]:data-ending-style:translate-y-[2.5rem] data-[side=bottom]:data-starting-style:translate-y-[2.5rem] data-[side=left]:inset-y-0 data-[side=left]:left-0 data-[side=left]:h-full data-[side=left]:w-3/4 data-[side=left]:border-r data-[side=left]:data-ending-style:translate-x-[-2.5rem] data-[side=left]:data-starting-style:translate-x-[-2.5rem] data-[side=right]:inset-y-0 data-[side=right]:right-0 data-[side=right]:h-full data-[side=right]:w-3/4 data-[side=right]:border-l data-[side=right]:data-ending-style:translate-x-[2.5rem] data-[side=right]:data-starting-style:translate-x-[2.5rem] data-[side=top]:inset-x-0 data-[side=top]:top-0 data-[side=top]:h-auto data-[side=top]:border-b data-[side=top]:data-ending-style:translate-y-[-2.5rem] data-[side=top]:data-starting-style:translate-y-[-2.5rem] data-[side=left]:sm:max-w-sm data-[side=right]:sm:max-w-sm motion-reduce:transition-none",
+          className,
+        )}
+        {...props}
+      >
+        {children}
+        {showCloseButton && (
+          <SheetPrimitive.Close
+            data-slot="sheet-close"
+            render={
+              <Button
+                variant="ghost"
+                className="absolute top-4 right-4"
+                size="sm"
+              />
+            }
+          >
+            <XIcon aria-hidden="true" />
+            <span className="sr-only">Close</span>
+          </SheetPrimitive.Close>
+        )}
+      </SheetPrimitive.Popup>
+    </>
+  );
+}
+
+function SheetHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sheet-header"
+      className={cn("flex flex-col gap-0.5 p-4", className)}
+      {...props}
+    />
+  );
+}
+
+function SheetFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sheet-footer"
+      className={cn("mt-auto flex flex-col gap-2 p-4", className)}
+      {...props}
+    />
+  );
+}
+
+function SheetTitle({ className, ...props }: SheetPrimitive.Title.Props) {
+  return (
+    <SheetPrimitive.Title
+      data-slot="sheet-title"
+      className={cn(
+        "font-heading text-base font-medium text-foreground",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function SheetDescription({
+  className,
+  ...props
+}: SheetPrimitive.Description.Props) {
+  return (
+    <SheetPrimitive.Description
+      data-slot="sheet-description"
+      className={cn("text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  );
+}
+
+export {
+  Sheet,
+  SheetClose,
+  SheetContent,
+  SheetDescription,
+  SheetFooter,
+  SheetHeader,
+  SheetOverlay,
+  SheetPortal,
+  SheetTitle,
+  SheetTrigger,
+};

package/src/components/micro/sidebar.tsx

@@ -0,0 +1,238 @@
+import { cn } from "../../lib/utils";
+import * as React from "react";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 1. Sidebar (Wrapper)
+// ─────────────────────────────────────────────────────────────────────────────
+const Sidebar = React.forwardRef<
+  HTMLDivElement,
+  React.ComponentProps<"div"> & {
+    defaultState?: "expanded" | "collapsed";
+    /** Width in pixels when expanded. Default: 256 (= w-64) */
+    expandedWidth?: number;
+    /** Width in pixels when collapsed. Default: 56 (= w-14) */
+    collapsedWidth?: number;
+  }
+>(
+  (
+    {
+      className,
+      defaultState = "expanded",
+      expandedWidth = 256,
+      collapsedWidth = 72,
+      ...props
+    },
+    ref,
+  ) => {
+    // will-change only during animation, not always-on
+    const handleTransitionStart = (
+      e: React.TransitionEvent<HTMLDivElement>,
+    ) => {
+      if (e.propertyName === "width")
+        e.currentTarget.style.willChange = "width";
+    };
+    const handleTransitionEnd = (e: React.TransitionEvent<HTMLDivElement>) => {
+      if (e.propertyName === "width") e.currentTarget.style.willChange = "auto";
+    };
+
+    return (
+      // Outer: only this div animates width. No layout children to reflow.
+      <div
+        ref={ref}
+        role="navigation"
+        aria-expanded={defaultState === "expanded"}
+        style={
+          {
+            "--sb-expanded": `${expandedWidth}px`,
+            "--sb-collapsed": `${collapsedWidth}px`,
+          } as React.CSSProperties
+        }
+        className={cn(
+          "group shrink-0 h-full overflow-hidden border-r border-r-border bg-sidebar text-sidebar-foreground",
+          "transition-[width,border-width] duration-[400ms]",
+          "data-[state=expanded]:w-[var(--sb-expanded)]",
+          "data-[state=collapsed]:w-[var(--sb-collapsed)]",
+          collapsedWidth === 0 && "data-[state=collapsed]:border-r-0",
+          className,
+        )}
+        data-state={defaultState}
+        onTransitionStart={handleTransitionStart}
+        onTransitionEnd={handleTransitionEnd}
+      >
+        {/* Inner: ALWAYS expandedWidth. Never relayouts. Clipped by outer overflow-hidden. */}
+        <div
+          className="flex h-full flex-col p-2"
+          style={{ width: `${expandedWidth}px` }}
+          {...props}
+        />
+      </div>
+    );
+  },
+);
+Sidebar.displayName = "Sidebar";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 2. SidebarLogo
+// ─────────────────────────────────────────────────────────────────────────────
+const SidebarLogo = React.forwardRef<
+  HTMLDivElement,
+  React.ComponentProps<"div"> & {
+    icon: React.ReactNode;
+    text: React.ReactNode;
+  }
+>(({ className, icon, text, ...props }, ref) => {
+  return (
+    <div
+      ref={ref}
+      className={cn(
+        "flex h-12 items-center overflow-hidden text-sidebar-foreground",
+        className,
+      )}
+      {...props}
+    >
+      {/* Icon container width matches collapsed sidebar width — reads CSS var from parent */}
+      <div
+        className="flex shrink-0 items-center justify-center"
+        style={{ width: "calc(var(--sb-collapsed) - 16px)" }}
+      >
+        {icon}
+      </div>
+      <span className="whitespace-nowrap font-semibold transition-opacity group-data-[state=collapsed]:opacity-0 group-data-[state=collapsed]:duration-[80ms] group-data-[state=expanded]:duration-[200ms] group-data-[state=expanded]:delay-[300ms]">
+        {text}
+      </span>
+    </div>
+  );
+});
+SidebarLogo.displayName = "SidebarLogo";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 3. SidebarLabel
+// ─────────────────────────────────────────────────────────────────────────────
+const SidebarLabel = React.forwardRef<
+  HTMLDivElement,
+  React.ComponentProps<"div"> & {
+    icon: React.ReactNode;
+    text: React.ReactNode;
+  }
+>(({ className, icon, text, ...props }, ref) => {
+  return (
+    <div
+      ref={ref}
+      className={cn(
+        "flex h-10 items-center overflow-hidden text-sm text-sidebar-foreground",
+        "hover:bg-sidebar-accent hover:text-sidebar-accent-foreground cursor-pointer rounded-md",
+        className,
+      )}
+      {...props}
+    >
+      {/* Icon container width matches collapsed sidebar width — reads CSS var from parent */}
+      <div
+        className="flex shrink-0 items-center justify-center [&>svg]:size-4"
+        style={{ width: "calc(var(--sb-collapsed) - 16px)" }}
+      >
+        {icon}
+      </div>
+      <span className="whitespace-nowrap transition-opacity group-data-[state=collapsed]:opacity-0 group-data-[state=collapsed]:duration-[80ms] group-data-[state=expanded]:duration-[200ms] group-data-[state=expanded]:delay-[300ms]">
+        {text}
+      </span>
+    </div>
+  );
+});
+SidebarLabel.displayName = "SidebarLabel";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 4. SidebarMenuItemList
+// ─────────────────────────────────────────────────────────────────────────────
+const SidebarMenuItemList = React.forwardRef<
+  HTMLDivElement,
+  React.ComponentProps<"div">
+>(({ className, ...props }, ref) => {
+  return (
+    <div
+      ref={ref}
+      className={cn("flex flex-col gap-1", className)}
+      {...props}
+    />
+  );
+});
+SidebarMenuItemList.displayName = "SidebarMenuItemList";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 5. SidebarMenuItem
+// ─────────────────────────────────────────────────────────────────────────────
+const SidebarMenuItem = React.forwardRef<
+  HTMLDivElement,
+  React.ComponentProps<"div"> & {
+    text: React.ReactNode;
+  }
+>(({ className, text, ...props }, ref) => {
+  return (
+    <div
+      ref={ref}
+      className={cn(
+        "flex h-8 items-center pr-4 text-sm text-sidebar-foreground/70",
+        "hover:bg-sidebar-accent hover:text-sidebar-accent-foreground cursor-pointer rounded-md",
+        className,
+      )}
+      // Indent aligns with label text, which starts after the icon column (--sb-collapsed wide)
+      style={{ paddingLeft: "calc(var(--sb-collapsed) - 16px)" }}
+      {...props}
+    >
+      <span className="whitespace-nowrap transition-opacity group-data-[state=collapsed]:opacity-0 group-data-[state=collapsed]:duration-[80ms] group-data-[state=expanded]:duration-[200ms] group-data-[state=expanded]:delay-[300ms]">
+        {text}
+      </span>
+    </div>
+  );
+});
+SidebarMenuItem.displayName = "SidebarMenuItem";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 6. Imperative Toggle Hook
+// ─────────────────────────────────────────────────────────────────────────────
+export function useSidebarToggle(
+  initialState: "expanded" | "collapsed" = "expanded",
+  onStateChange?: (state: "expanded" | "collapsed") => void,
+) {
+  const sidebarRef = React.useRef<HTMLDivElement>(null);
+  // Stable ref so setSidebarState callback never goes stale even if caller's onStateChange changes
+  const onStateChangeRef = React.useRef(onStateChange);
+  React.useEffect(() => {
+    onStateChangeRef.current = onStateChange;
+  }, [onStateChange]);
+
+  const setSidebarState = React.useCallback(
+    (state: "expanded" | "collapsed") => {
+      if (sidebarRef.current) {
+        sidebarRef.current.setAttribute("data-state", state);
+        sidebarRef.current.setAttribute(
+          "aria-expanded",
+          String(state === "expanded"),
+        );
+        onStateChangeRef.current?.(state);
+      }
+    },
+    [],
+  );
+
+  const toggleSidebar = React.useCallback(() => {
+    if (sidebarRef.current) {
+      const current = sidebarRef.current.getAttribute("data-state");
+      setSidebarState(current === "expanded" ? "collapsed" : "expanded");
+    }
+  }, [setSidebarState]);
+
+  return {
+    sidebarRef,
+    toggleSidebar,
+    setSidebarState,
+    defaultState: initialState,
+  };
+}
+
+export {
+  Sidebar,
+  SidebarLabel,
+  SidebarLogo,
+  SidebarMenuItem,
+  SidebarMenuItemList,
+};

package/src/components/micro/skeleton.tsx

@@ -0,0 +1,29 @@
+/**
+ * ✅ AUDITED & REFACTORED
+ * - Design System Compliant (22 Commandments)
+ * - WCAG AAA/AA
+ * - Form Control Parity
+ * - CSS Delegated Logic
+ */
+import { cn } from "../../lib/utils";
+import * as React from "react";
+
+/**
+ * @description Use to show a placeholder while content is loading.
+ * @example
+ * <Skeleton className="w-[100px] h-[20px] rounded-full" />
+ */
+const Skeleton = React.forwardRef<
+  HTMLDivElement,
+  React.ComponentPropsWithoutRef<"div">
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    data-slot="skeleton"
+    className={cn("animate-pulse rounded-lg bg-muted", className)}
+    {...props}
+  />
+));
+Skeleton.displayName = "Skeleton";
+
+export { Skeleton };