@cntyclub/ui-react 0.4.1 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cntyclub/ui-react",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "React component library for the Country Club UI Kit — Base UI primitives styled with the Country Club design system (Tailwind CSS v4)",
   "type": "module",
   "sideEffects": [
@@ -28,6 +28,33 @@
     "dist"
   ],
   "comment-publishConfig": "In-repo (docs/storybook/vue) consume src/ via the exports above. When PUBLISHED to a registry, npm/pnpm swap in these fields so external installs get the compiled, self-contained dist/ (tsup bundles every dependency except react/react-dom) — no transpilePackages, no heavy transitive dep tree.",
+  "publishConfig": {
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js",
+        "default": "./dist/index.js"
+      },
+      "./form": {
+        "types": "./dist/form.d.ts",
+        "import": "./dist/form.js",
+        "default": "./dist/form.js"
+      },
+      "./styles.css": "./src/styles.css",
+      "./package.json": "./package.json"
+    },
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\"",
+    "prepublishOnly": "tsup"
+  },
   "dependencies": {
     "@base-ui/react": "1.1.0",
     "@headlessui/react": "^2.2.9",
@@ -64,18 +91,12 @@
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
+    "@countryclub/typescript-config": "workspace:*",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "tsup": "^8.4.0",
-    "typescript": "^5.8.3",
-    "@countryclub/typescript-config": "0.1.0"
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "clean": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\""
+    "typescript": "^5.8.3"
   }
-}
+}

package/src/components/ui/help-tip.tsx

@@ -0,0 +1,94 @@
+"use client";
+
+import { CircleHelp } from "lucide-react";
+import type * as React from "react";
+
+import { cn } from "../../lib/utils/css";
+import {
+  Tooltip,
+  TooltipDescription,
+  TooltipPopup,
+  TooltipProvider,
+  TooltipTitle,
+  TooltipTrigger,
+} from "./tooltip";
+
+export interface HelpTipProps {
+  /** The help text shown in the tooltip. */
+  children?: React.ReactNode;
+  /** Optional bold heading rendered above the description text. */
+  title?: React.ReactNode;
+  /** Which side of the trigger the tooltip opens on. Default "top". */
+  side?: React.ComponentProps<typeof TooltipPopup>["side"];
+  /** Alignment of the tooltip along the trigger. Default "center". */
+  align?: React.ComponentProps<typeof TooltipPopup>["align"];
+  /** Accessible label for the icon button. Default "More information". */
+  label?: string;
+  /** Hover / focus open delay in ms. Default 150. */
+  delay?: number;
+  /** Icon size in px. Default 16. */
+  iconSize?: number;
+  /** Extra classes for the trigger button. */
+  className?: string;
+  /** Extra classes for the tooltip popup. */
+  popupClassName?: string;
+  /** Render the little arrow pointing at the icon. Default false. */
+  arrow?: boolean;
+}
+
+/**
+ * A small "?" help affordance: an unobtrusive circular icon that reveals
+ * supporting text in a tooltip on hover / focus. Use it next to a label,
+ * heading, or field when a short explanation would help but shouldn't take up
+ * permanent space.
+ *
+ * ```tsx
+ * <span className="flex items-center gap-1.5">
+ *   My Events
+ *   <HelpTip>Every event Country Club has surfaced for you…</HelpTip>
+ * </span>
+ * ```
+ */
+export function HelpTip({
+  children,
+  title,
+  side = "top",
+  align = "center",
+  label = "More information",
+  delay = 150,
+  iconSize = 16,
+  className,
+  popupClassName,
+  arrow = false,
+}: HelpTipProps) {
+  return (
+    <TooltipProvider delay={delay}>
+      <Tooltip>
+        <TooltipTrigger
+          aria-label={label}
+          className={cn(
+            "inline-flex shrink-0 cursor-help items-center justify-center rounded-full text-muted-foreground outline-none transition-colors hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring",
+            className,
+          )}
+        >
+          <CircleHelp aria-hidden size={iconSize} />
+        </TooltipTrigger>
+        <TooltipPopup
+          align={align}
+          arrow={arrow}
+          className={cn("max-w-64 [--viewport-inline-padding:--spacing(3)]", popupClassName)}
+          side={side}
+        >
+          {title ? (
+            <div className="flex flex-col gap-0.5 py-0.5">
+              <TooltipTitle>{title}</TooltipTitle>
+              <TooltipDescription className="text-popover-foreground">{children}</TooltipDescription>
+            </div>
+          ) : (
+            <div className="py-0.5 leading-snug">{children}</div>
+          )}
+        </TooltipPopup>
+      </Tooltip>
+    </TooltipProvider>
+  );
+}

package/src/components/ui/sidebar.tsx

@@ -58,6 +58,7 @@ function SidebarProvider({
   defaultOpen = true,
   open: openProp,
   onOpenChange: setOpenProp,
+  persistKey,
   className,
   style,
   children,
@@ -66,6 +67,14 @@ function SidebarProvider({
   defaultOpen?: boolean;
   open?: boolean;
   onOpenChange?: (open: boolean) => void;
+  /**
+   * Remember the expanded/collapsed state in `localStorage` under this key and
+   * restore it on the next load (desktop rail only; the mobile sheet is always
+   * closed on load). Opt-in — omit to keep the sidebar un-persisted. Ignored in
+   * controlled mode (when `open` is provided). The restore runs before first
+   * paint, so there's no expand→collapse flash.
+   */
+  persistKey?: string;
 }) {
   // Self-contained breakpoint check (md = 48rem). Resolved in a layout effect
   // before the first paint so the sidebar never flashes from mobile to desktop.
@@ -93,16 +102,38 @@ function SidebarProvider({
       }
 
       // Persist the sidebar state. document.cookie works in every browser
-      // (cookieStore is Chromium-only and throws elsewhere).
+      // (cookieStore is Chromium-only and throws elsewhere). When `persistKey`
+      // is set we also mirror it to localStorage so a client-only app (no SSR
+      // cookie read) can restore it on load.
       try {
         document.cookie = `${SIDEBAR_COOKIE_NAME}=${openState}; path=/; max-age=${SIDEBAR_COOKIE_MAX_AGE}`;
+        if (persistKey) {
+          window.localStorage.setItem(persistKey, openState ? "true" : "false");
+        }
       } catch {
         // Ignore — persistence is best-effort.
       }
     },
-    [setOpenProp, open],
+    [setOpenProp, open, persistKey],
   );
 
+  // Restore the persisted (localStorage) open state on mount — uncontrolled use
+  // only. Runs in a layout effect so the restore lands before first paint (no
+  // expand→collapse flash). SSR renders `defaultOpen` and the client's first
+  // render matches it, so this reconciles afterwards without a hydration
+  // mismatch.
+  useIsomorphicLayoutEffect(() => {
+    if (!persistKey || openProp !== undefined) return;
+    try {
+      const stored = window.localStorage.getItem(persistKey);
+      if (stored === "true" || stored === "false") {
+        _setOpen(stored === "true");
+      }
+    } catch {
+      // Ignore — restore is best-effort.
+    }
+  }, [persistKey, openProp]);
+
   // Helper to toggle the sidebar.
   const toggleSidebar = React.useCallback(() => {
     return isMobile ? setOpenMobile((open) => !open) : setOpen((open) => !open);

package/src/index.ts

@@ -39,6 +39,7 @@ export * from "./components/ui/form";
 export * from "./components/ui/frame";
 export * from "./components/ui/generic-empty";
 export * from "./components/ui/group";
+export * from "./components/ui/help-tip";
 export * from "./components/ui/horizontal-scroll-fader";
 export * from "./components/ui/input";
 export * from "./components/ui/input-group";