@dowel-ui/react 0.1.0

package/src/components/tooltip/index.ts

@@ -0,0 +1,8 @@
+export {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+  type TooltipContentProps,
+  type TooltipProps,
+} from "./tooltip";

package/src/components/tooltip/meta.ts

@@ -0,0 +1,17 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "tooltip",
+  title: "Tooltip",
+  description: "A short label revealed on hover or keyboard focus.",
+  category: "overlay",
+  status: "stable",
+  dependencies: ["radix-ui"],
+  registryDependencies: [],
+  files: ["tooltip.tsx"],
+  a11y:
+    "Opens on focus as well as hover, and Escape dismisses it. Never put essential or " +
+    "interactive content in a tooltip: it is unreachable on touch and vanishes on blur. For an " +
+    "icon-only button, prefer aria-label for the name and use the tooltip only to repeat it " +
+    "visually.",
+});

package/src/components/tooltip/tooltip.stories.tsx

@@ -0,0 +1,89 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Bold, Italic, Underline } from "lucide-react";
+
+import { Button } from "@/components/button";
+
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "./tooltip";
+
+const meta = {
+  title: "Overlays/Tooltip",
+  component: Tooltip,
+  args: { delayDuration: 200 },
+  argTypes: {
+    delayDuration: { control: { type: "number", min: 0, max: 1000, step: 50 } },
+  },
+} satisfies Meta<typeof Tooltip>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: (args) => (
+    <Tooltip {...args}>
+      <TooltipTrigger asChild>
+        <Button variant="outline">Hover or focus me</Button>
+      </TooltipTrigger>
+      <TooltipContent>Deploys the current branch</TooltipContent>
+    </Tooltip>
+  ),
+};
+
+/**
+ * On an icon-only control the accessible name comes from aria-label. The
+ * tooltip repeats it visually; it does not supply it.
+ */
+export const IconButtons: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <TooltipProvider delayDuration={150}>
+      <div className="flex items-center gap-1">
+        {[
+          { icon: Bold, label: "Bold" },
+          { icon: Italic, label: "Italic" },
+          { icon: Underline, label: "Underline" },
+        ].map(({ icon: Icon, label }) => (
+          <Tooltip key={label}>
+            <TooltipTrigger asChild>
+              <Button variant="ghost" size="icon" aria-label={label}>
+                <Icon />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent>{label}</TooltipContent>
+          </Tooltip>
+        ))}
+      </div>
+    </TooltipProvider>
+  ),
+};
+
+export const Sides: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <TooltipProvider delayDuration={0}>
+      <div className="flex flex-wrap gap-3">
+        {(["top", "right", "bottom", "left"] as const).map((side) => (
+          <Tooltip key={side}>
+            <TooltipTrigger asChild>
+              <Button variant="outline">{side}</Button>
+            </TooltipTrigger>
+            <TooltipContent side={side}>Anchored {side}</TooltipContent>
+          </Tooltip>
+        ))}
+      </div>
+    </TooltipProvider>
+  ),
+};
+
+export const LongText: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Tooltip delayDuration={0}>
+      <TooltipTrigger asChild>
+        <Button variant="outline">Retention</Button>
+      </TooltipTrigger>
+      <TooltipContent>
+        Logs are kept for 30 days on the current plan, then aggregated into daily summaries.
+      </TooltipContent>
+    </Tooltip>
+  ),
+};

package/src/components/tooltip/tooltip.test.tsx

@@ -0,0 +1,120 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it } from "vitest";
+
+import { expectNoA11yViolations } from "../../../test/a11y";
+import { Button } from "../button";
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "./tooltip";
+
+function Example({ delayDuration = 0 }: { delayDuration?: number } = {}) {
+  return (
+    <Tooltip delayDuration={delayDuration}>
+      <TooltipTrigger asChild>
+        <Button size="icon" aria-label="Add item">
+          +
+        </Button>
+      </TooltipTrigger>
+      <TooltipContent>Add item</TooltipContent>
+    </Tooltip>
+  );
+}
+
+describe("Tooltip", () => {
+  it("is hidden until the trigger is hovered", async () => {
+    const user = userEvent.setup();
+    render(<Example />);
+
+    expect(screen.queryByRole("tooltip")).not.toBeInTheDocument();
+    await user.hover(screen.getByRole("button", { name: "Add item" }));
+    expect(await screen.findByRole("tooltip")).toHaveTextContent("Add item");
+  });
+
+  it("opens on keyboard focus, not only on hover", async () => {
+    const user = userEvent.setup();
+    render(<Example />);
+
+    await user.tab();
+    expect(screen.getByRole("button", { name: "Add item" })).toHaveFocus();
+    expect(await screen.findByRole("tooltip")).toBeInTheDocument();
+  });
+
+  it("closes when the pointer leaves", async () => {
+    const user = userEvent.setup();
+    // disableHoverableContent removes the grace area that normally lets the
+    // pointer travel from trigger to tooltip. That grace area is a polygon
+    // computed from measured rects, and jsdom reports every rect as zero-sized,
+    // so leaving it enabled would exercise the stub rather than the behaviour.
+    render(
+      <Tooltip delayDuration={0} disableHoverableContent>
+        <TooltipTrigger>Trigger</TooltipTrigger>
+        <TooltipContent>Hint</TooltipContent>
+      </Tooltip>,
+    );
+
+    const trigger = screen.getByText("Trigger");
+    await user.hover(trigger);
+    await screen.findByRole("tooltip");
+
+    await user.unhover(trigger);
+    await waitFor(() => {
+      expect(screen.queryByRole("tooltip")).not.toBeInTheDocument();
+    });
+  });
+
+  it("closes on Escape", async () => {
+    const user = userEvent.setup();
+    render(<Example />);
+
+    await user.tab();
+    await screen.findByRole("tooltip");
+
+    await user.keyboard("{Escape}");
+    await waitFor(() => {
+      expect(screen.queryByRole("tooltip")).not.toBeInTheDocument();
+    });
+  });
+
+  it("works without an explicit provider", async () => {
+    const user = userEvent.setup();
+    render(<Example />);
+
+    await user.hover(screen.getByRole("button", { name: "Add item" }));
+    expect(await screen.findByRole("tooltip")).toBeInTheDocument();
+  });
+
+  it("works inside a shared provider", async () => {
+    const user = userEvent.setup();
+    render(
+      <TooltipProvider delayDuration={0}>
+        <Example />
+      </TooltipProvider>,
+    );
+
+    await user.hover(screen.getByRole("button", { name: "Add item" }));
+    expect(await screen.findByRole("tooltip")).toBeInTheDocument();
+  });
+
+  it("merges a consumer className", async () => {
+    const user = userEvent.setup();
+    render(
+      <Tooltip delayDuration={0}>
+        <TooltipTrigger>Trigger</TooltipTrigger>
+        <TooltipContent className="max-w-xs">Hint</TooltipContent>
+      </Tooltip>,
+    );
+
+    await user.hover(screen.getByText("Trigger"));
+    const tooltip = await screen.findByRole("tooltip");
+    expect(tooltip).toHaveClass("max-w-xs");
+    expect(tooltip).not.toHaveClass("max-w-64");
+  });
+
+  it("has no accessibility violations while open", async () => {
+    const user = userEvent.setup();
+    const { baseElement } = render(<Example />);
+    await user.hover(screen.getByRole("button", { name: "Add item" }));
+    await screen.findByRole("tooltip");
+
+    await expectNoA11yViolations(baseElement);
+  });
+});

package/src/components/tooltip/tooltip.tsx

@@ -0,0 +1,58 @@
+"use client";
+
+import { Tooltip as TooltipPrimitive } from "radix-ui";
+import type { ComponentPropsWithRef } from "react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * A short label revealed on hover or focus.
+ *
+ * A tooltip supplements a control that is already understandable — it must
+ * never be the only place information appears, because it is unreachable on
+ * touch devices and disappears the moment attention moves. If the content is
+ * essential, put it in the interface.
+ */
+export const TooltipProvider = TooltipPrimitive.Provider;
+export const TooltipTrigger = TooltipPrimitive.Trigger;
+
+export type TooltipProps = ComponentPropsWithRef<typeof TooltipPrimitive.Root>;
+
+/**
+ * Self-providing, so a single tooltip works without app-level setup. Wrap a
+ * subtree in TooltipProvider to share open/close timing across many tooltips.
+ */
+export function Tooltip({ children, ...props }: TooltipProps) {
+  return (
+    <TooltipPrimitive.Provider>
+      <TooltipPrimitive.Root {...props}>{children}</TooltipPrimitive.Root>
+    </TooltipPrimitive.Provider>
+  );
+}
+
+export type TooltipContentProps = ComponentPropsWithRef<typeof TooltipPrimitive.Content>;
+
+export function TooltipContent({
+  className,
+  sideOffset = 6,
+  children,
+  ...props
+}: TooltipContentProps) {
+  return (
+    <TooltipPrimitive.Portal>
+      <TooltipPrimitive.Content
+        data-slot="tooltip-content"
+        sideOffset={sideOffset}
+        className={cn(
+          "z-[var(--z-tooltip)] max-w-64 rounded-md bg-foreground px-2.5 py-1.5 text-xs text-background shadow-md",
+          "origin-[var(--radix-tooltip-content-transform-origin)] text-balance",
+          "data-[state=closed]:animate-float-out data-[state=delayed-open]:animate-float-in",
+          className,
+        )}
+        {...props}
+      >
+        {children}
+      </TooltipPrimitive.Content>
+    </TooltipPrimitive.Portal>
+  );
+}

package/src/index.ts

@@ -0,0 +1,50 @@
+export * from "./components/accordion";
+export * from "./components/activity-feed";
+export * from "./components/ai-agent-status";
+export * from "./components/ai-conversation";
+export * from "./components/ai-message";
+export * from "./components/ai-model-selector";
+export * from "./components/ai-prompt-input";
+export * from "./components/ai-reasoning";
+export * from "./components/ai-response";
+export * from "./components/ai-sources";
+export * from "./components/ai-token-usage";
+export * from "./components/ai-tool";
+export * from "./components/alert";
+export * from "./components/avatar";
+export * from "./components/badge";
+export * from "./components/button";
+export * from "./components/calendar";
+export * from "./components/card";
+export * from "./components/checkbox";
+export * from "./components/code-block";
+export * from "./components/combobox";
+export * from "./components/command";
+export * from "./components/data-table";
+export * from "./components/date-picker";
+export * from "./components/dialog";
+export * from "./components/drawer";
+export * from "./components/dropdown-menu";
+export * from "./components/empty-state";
+export * from "./components/form";
+export * from "./components/input";
+export * from "./components/label";
+export * from "./components/pagination";
+export * from "./components/popover";
+export * from "./components/progress";
+export * from "./components/radio-group";
+export * from "./components/select";
+export * from "./components/separator";
+export * from "./components/sheet";
+export * from "./components/skeleton";
+export * from "./components/slider";
+export * from "./components/spinner";
+export * from "./components/switch";
+export * from "./components/table";
+export * from "./components/tabs";
+export * from "./components/toast";
+export * from "./components/tooltip";
+
+export { cn } from "./lib/utils";
+export * from "./lib/styles";
+export * from "./registry/schema";

package/src/lib/styles.ts

@@ -0,0 +1,26 @@
+/**
+ * Style fragments shared across components.
+ *
+ * These exist so interaction states are defined once. If focus rings or
+ * disabled treatment need to change, they change here and every component
+ * follows — which is what keeps the system visually coherent (design spec §12).
+ */
+
+/** Keyboard focus ring. Deliberately not applied on pointer focus. */
+export const focusRing =
+  "outline-none focus-visible:ring-2 focus-visible:ring-ring/55 focus-visible:ring-offset-2 focus-visible:ring-offset-background";
+
+/** Focus ring for controls that sit flush inside a bordered container. */
+export const focusRingInset = "outline-none focus-visible:ring-2 focus-visible:ring-ring/55";
+
+/** Applied to natively disabled elements and `aria-disabled` ones alike. */
+export const disabledStyles =
+  "disabled:pointer-events-none disabled:opacity-55 aria-disabled:pointer-events-none aria-disabled:opacity-55";
+
+/** Invalid-state treatment driven by `aria-invalid`, never by a bespoke prop. */
+export const invalidStyles =
+  "aria-invalid:border-destructive aria-invalid:focus-visible:ring-destructive/40";
+
+/** Sizes any icon rendered as a direct child of a control. */
+export const iconSlot =
+  "[&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4";

package/src/lib/utils.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+
+import { cn } from "./utils";
+
+describe("cn", () => {
+  it("joins class names", () => {
+    expect(cn("a", "b")).toBe("a b");
+  });
+
+  it("drops falsy values", () => {
+    expect(cn("a", false, undefined, null, "b")).toBe("a b");
+  });
+
+  it("lets the later Tailwind utility win a conflict", () => {
+    expect(cn("px-2", "px-4")).toBe("px-4");
+  });
+
+  it("resolves conflicts across our custom font-size scale", () => {
+    // Without the extendTailwindMerge config this returns "text-sm text-2xs",
+    // and a consumer's size override would silently do nothing.
+    expect(cn("text-sm", "text-2xs")).toBe("text-2xs");
+    expect(cn("text-2xs", "text-lg")).toBe("text-lg");
+  });
+
+  it("keeps non-conflicting utilities", () => {
+    expect(cn("rounded-md border", "bg-primary")).toBe("rounded-md border bg-primary");
+  });
+
+  it("accepts arrays and objects", () => {
+    expect(cn(["a", { b: true, c: false }])).toBe("a b");
+  });
+});

package/src/lib/utils.ts

@@ -0,0 +1,24 @@
+import { clsx, type ClassValue } from "clsx";
+import { extendTailwindMerge } from "tailwind-merge";
+
+/**
+ * tailwind-merge does not know about scales we add on top of Tailwind's
+ * defaults, so `text-2xs` would be misclassified and fail to override
+ * `text-sm`. Registering our additions keeps class conflict resolution correct.
+ */
+const twMerge = extendTailwindMerge({
+  extend: {
+    classGroups: {
+      "font-size": [{ text: ["2xs"] }],
+    },
+  },
+});
+
+/**
+ * Merges class names, with later Tailwind utilities winning over earlier
+ * conflicting ones. Every component runs its `className` prop through this so
+ * consumers can override any style without `!important`.
+ */
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}

package/src/registry/blocks.ts

@@ -0,0 +1,30 @@
+import type { ComponentMeta } from "./schema";
+
+import { meta as adminUsersMeta } from "@/blocks/admin-users/meta";
+import { meta as aiChatMeta } from "@/blocks/ai-chat/meta";
+import { meta as dashboardMeta } from "@/blocks/dashboard/meta";
+import { meta as forgotPasswordMeta } from "@/blocks/forgot-password/meta";
+import { meta as loginMeta } from "@/blocks/login/meta";
+import { meta as pricingMeta } from "@/blocks/pricing/meta";
+import { meta as settingsMeta } from "@/blocks/settings/meta";
+import { meta as signupMeta } from "@/blocks/signup/meta";
+
+/**
+ * Every block in the registry.
+ *
+ * Kept separate from `componentMetas` for the same reason blocks install into a
+ * different directory: they are whole page sections, browsed and used
+ * differently from the components they are assembled out of.
+ *
+ * `meta.test.ts` fails if a block directory exists that is missing from here.
+ */
+export const blockMetas: ComponentMeta[] = [
+  adminUsersMeta,
+  aiChatMeta,
+  dashboardMeta,
+  forgotPasswordMeta,
+  loginMeta,
+  pricingMeta,
+  settingsMeta,
+  signupMeta,
+];

package/src/registry/components.ts

@@ -0,0 +1,114 @@
+import type { ComponentMeta } from "./schema";
+
+import { meta as accordionMeta } from "@/components/accordion/meta";
+import { meta as activityFeedMeta } from "@/components/activity-feed/meta";
+import { meta as aiAgentStatusMeta } from "@/components/ai-agent-status/meta";
+import { meta as aiConversationMeta } from "@/components/ai-conversation/meta";
+import { meta as aiMessageMeta } from "@/components/ai-message/meta";
+import { meta as aiModelSelectorMeta } from "@/components/ai-model-selector/meta";
+import { meta as aiPromptInputMeta } from "@/components/ai-prompt-input/meta";
+import { meta as aiReasoningMeta } from "@/components/ai-reasoning/meta";
+import { meta as aiResponseMeta } from "@/components/ai-response/meta";
+import { meta as aiSourcesMeta } from "@/components/ai-sources/meta";
+import { meta as aiTokenUsageMeta } from "@/components/ai-token-usage/meta";
+import { meta as aiToolMeta } from "@/components/ai-tool/meta";
+import { meta as alertMeta } from "@/components/alert/meta";
+import { meta as avatarMeta } from "@/components/avatar/meta";
+import { meta as badgeMeta } from "@/components/badge/meta";
+import { meta as buttonMeta } from "@/components/button/meta";
+import { meta as calendarMeta } from "@/components/calendar/meta";
+import { meta as cardMeta } from "@/components/card/meta";
+import { meta as checkboxMeta } from "@/components/checkbox/meta";
+import { meta as codeBlockMeta } from "@/components/code-block/meta";
+import { meta as comboboxMeta } from "@/components/combobox/meta";
+import { meta as commandMeta } from "@/components/command/meta";
+import { meta as dataTableMeta } from "@/components/data-table/meta";
+import { meta as datePickerMeta } from "@/components/date-picker/meta";
+import { meta as dialogMeta } from "@/components/dialog/meta";
+import { meta as drawerMeta } from "@/components/drawer/meta";
+import { meta as dropdownMenuMeta } from "@/components/dropdown-menu/meta";
+import { meta as emptyStateMeta } from "@/components/empty-state/meta";
+import { meta as formMeta } from "@/components/form/meta";
+import { meta as inputMeta } from "@/components/input/meta";
+import { meta as labelMeta } from "@/components/label/meta";
+import { meta as paginationMeta } from "@/components/pagination/meta";
+import { meta as popoverMeta } from "@/components/popover/meta";
+import { meta as progressMeta } from "@/components/progress/meta";
+import { meta as radioGroupMeta } from "@/components/radio-group/meta";
+import { meta as selectMeta } from "@/components/select/meta";
+import { meta as separatorMeta } from "@/components/separator/meta";
+import { meta as sheetMeta } from "@/components/sheet/meta";
+import { meta as skeletonMeta } from "@/components/skeleton/meta";
+import { meta as sliderMeta } from "@/components/slider/meta";
+import { meta as spinnerMeta } from "@/components/spinner/meta";
+import { meta as switchMeta } from "@/components/switch/meta";
+import { meta as tableMeta } from "@/components/table/meta";
+import { meta as tabsMeta } from "@/components/tabs/meta";
+import { meta as toastMeta } from "@/components/toast/meta";
+import { meta as tooltipMeta } from "@/components/tooltip/meta";
+
+/**
+ * Every component in the registry.
+ *
+ * An explicit list rather than a glob: the registry build runs in plain Node,
+ * where bundler-only globbing is unavailable, and a static list is also what
+ * lets the bundle tree-shake. `meta.test.ts` fails if a component directory
+ * exists that is missing from here, so it cannot silently fall out of date.
+ *
+ * Identifiers carry a `Meta` suffix because component names include reserved
+ * words — `switch` cannot be a binding name.
+ */
+export const componentMetas: ComponentMeta[] = [
+  accordionMeta,
+  activityFeedMeta,
+  aiAgentStatusMeta,
+  aiConversationMeta,
+  aiMessageMeta,
+  aiModelSelectorMeta,
+  aiPromptInputMeta,
+  aiReasoningMeta,
+  aiResponseMeta,
+  aiSourcesMeta,
+  aiTokenUsageMeta,
+  aiToolMeta,
+  alertMeta,
+  avatarMeta,
+  badgeMeta,
+  buttonMeta,
+  calendarMeta,
+  cardMeta,
+  checkboxMeta,
+  codeBlockMeta,
+  comboboxMeta,
+  commandMeta,
+  dataTableMeta,
+  datePickerMeta,
+  dialogMeta,
+  drawerMeta,
+  dropdownMenuMeta,
+  emptyStateMeta,
+  formMeta,
+  inputMeta,
+  labelMeta,
+  paginationMeta,
+  popoverMeta,
+  progressMeta,
+  radioGroupMeta,
+  selectMeta,
+  separatorMeta,
+  sheetMeta,
+  skeletonMeta,
+  sliderMeta,
+  spinnerMeta,
+  switchMeta,
+  tableMeta,
+  tabsMeta,
+  toastMeta,
+  tooltipMeta,
+];
+
+// This file is the `@dowel-ui/react/registry` entry point, so the block barrel is
+// re-exported here — the registry build reads both through one import.
+export { blockMetas } from "./blocks";
+export { COMPONENT_CATEGORIES, COMPONENT_STATUSES } from "./schema";
+export type { ComponentCategory, ComponentMeta, ComponentStatus } from "./schema";