@dowel-ui/react 0.1.0

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@dowel-ui/react",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Source-first React components.",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./registry": {
+      "types": "./dist/registry/components.d.ts",
+      "default": "./dist/registry/components.js"
+    },
+    "./*": {
+      "types": "./dist/components/*/index.d.ts",
+      "default": "./dist/components/*/index.js"
+    }
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "dependencies": {
+    "@tanstack/react-table": "9.2.4",
+    "class-variance-authority": "0.7.1",
+    "clsx": "2.1.1",
+    "radix-ui": "1.6.7",
+    "react-day-picker": "10.0.1",
+    "tailwind-merge": "3.6.0"
+  },
+  "devDependencies": {
+    "@storybook/addon-a11y": "10.5.10",
+    "@storybook/addon-docs": "10.5.10",
+    "@storybook/react-vite": "10.5.10",
+    "@tailwindcss/vite": "4.3.3",
+    "@testing-library/jest-dom": "7.0.1",
+    "@testing-library/react": "16.3.3",
+    "@testing-library/user-event": "14.6.6",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.5",
+    "@vitejs/plugin-react": "6.1.1",
+    "@vitest/coverage-v8": "4.1.10",
+    "axe-core": "4.13.0",
+    "jsdom": "30.0.1",
+    "lucide-react": "1.38.0",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "storybook": "10.5.10",
+    "tailwindcss": "4.3.3",
+    "tsdown": "0.22.14",
+    "typescript": "6.0.3",
+    "vite": "8.2.2",
+    "vitest": "4.1.10",
+    "zod": "4.5.4",
+    "@dowel-ui/config": "0.1.0",
+    "@dowel-ui/themes": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "storybook": "storybook dev -p 6006 --no-open",
+    "build-storybook": "storybook build",
+    "clean": "rm -rf dist coverage storybook-static .turbo"
+  }
+}

package/src/blocks/admin-users/admin-users.stories.tsx

@@ -0,0 +1,83 @@
+import type { Decorator, Meta, StoryObj } from "@storybook/react-vite";
+
+import { AdminUsersBlock, type AdminUser } from "./admin-users";
+
+/** Named so its type is nameable in declaration output (TS2883). */
+const withPageWidth: Decorator = (Story) => (
+  <div className="w-[64rem] max-w-full">
+    <Story />
+  </div>
+);
+
+const USERS: AdminUser[] = [
+  {
+    id: "1",
+    name: "Ada Lovelace",
+    email: "ada@example.com",
+    role: "Owner",
+    status: "Active",
+    lastActive: "2 hours ago",
+  },
+  {
+    id: "2",
+    name: "Grace Hopper",
+    email: "grace@example.com",
+    role: "Admin",
+    status: "Active",
+    lastActive: "Yesterday",
+  },
+  {
+    id: "3",
+    name: "Katherine Johnson",
+    email: "kj@example.com",
+    role: "Member",
+    status: "Invited",
+    lastActive: "Never",
+  },
+  {
+    id: "4",
+    name: "Radia Perlman",
+    email: "radia@example.com",
+    role: "Viewer",
+    status: "Suspended",
+    lastActive: "3 weeks ago",
+  },
+  {
+    id: "5",
+    name: "Barbara Liskov",
+    email: "barbara@example.com",
+    role: "Member",
+    status: "Active",
+    lastActive: "5 minutes ago",
+  },
+  {
+    id: "6",
+    name: "Margaret Hamilton",
+    email: "margaret@example.com",
+    role: "Admin",
+    status: "Active",
+    lastActive: "Last week",
+  },
+];
+
+const meta = {
+  title: "Blocks/Admin — users",
+  component: AdminUsersBlock,
+  args: { users: USERS },
+  parameters: { controls: { disable: true } },
+  decorators: [withPageWidth],
+} satisfies Meta<typeof AdminUsersBlock>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Filter, sort and hide columns. The matching count is announced as you type. */
+export const Default: Story = {};
+
+export const Empty: Story = {
+  args: { users: [] },
+};
+
+export const SinglePerson: Story = {
+  args: { users: [USERS[0]!] },
+};

package/src/blocks/admin-users/admin-users.test.tsx

@@ -0,0 +1,159 @@
+import { render, screen, waitFor, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+
+import { expectNoA11yViolations } from "../../../test/a11y";
+import { AdminUsersBlock, type AdminUser } from "./admin-users";
+
+const USERS: AdminUser[] = [
+  {
+    id: "1",
+    name: "Ada Lovelace",
+    email: "ada@example.com",
+    role: "Owner",
+    status: "Active",
+    lastActive: "2 hours ago",
+  },
+  {
+    id: "2",
+    name: "Grace Hopper",
+    email: "grace@example.com",
+    role: "Admin",
+    status: "Active",
+    lastActive: "Yesterday",
+  },
+  {
+    id: "3",
+    name: "Katherine Johnson",
+    email: "kj@example.com",
+    role: "Member",
+    status: "Invited",
+    lastActive: "Never",
+  },
+  {
+    id: "4",
+    name: "Radia Perlman",
+    email: "radia@example.com",
+    role: "Viewer",
+    status: "Suspended",
+    lastActive: "3 weeks ago",
+  },
+];
+
+function rowCount(): number {
+  const body = screen.getAllByRole("rowgroup")[1];
+  return body ? within(body).queryAllByRole("row").length : 0;
+}
+
+describe("AdminUsersBlock", () => {
+  it("renders a row per user", () => {
+    render(<AdminUsersBlock users={USERS} />);
+    expect(rowCount()).toBe(4);
+  });
+
+  it("gives the filter a real label, not just a placeholder", () => {
+    render(<AdminUsersBlock users={USERS} />);
+    // A placeholder disappears the moment anyone types, taking the field's name
+    // with it.
+    expect(screen.getByLabelText("Filter by name or email")).toBeInTheDocument();
+  });
+
+  it("filters by name and by email", async () => {
+    const user = userEvent.setup();
+    render(<AdminUsersBlock users={USERS} />);
+
+    await user.type(screen.getByLabelText("Filter by name or email"), "grace");
+    await waitFor(() => {
+      expect(rowCount()).toBe(1);
+    });
+    expect(screen.getByText("Grace Hopper")).toBeInTheDocument();
+
+    await user.clear(screen.getByLabelText("Filter by name or email"));
+    await user.type(screen.getByLabelText("Filter by name or email"), "kj@example");
+    await waitFor(() => {
+      expect(screen.getByText("Katherine Johnson")).toBeInTheDocument();
+    });
+  });
+
+  it("announces the matching count, since results change unbidden", async () => {
+    const user = userEvent.setup();
+    const { container } = render(<AdminUsersBlock users={USERS} />);
+
+    const status = container.querySelector("[aria-live='polite']");
+    expect(status).toHaveTextContent("4 people match the filter.");
+
+    await user.type(screen.getByLabelText("Filter by name or email"), "grace");
+    await waitFor(() => {
+      expect(status).toHaveTextContent("1 person match");
+    });
+  });
+
+  it("shows an empty state naming the query that found nothing", async () => {
+    const user = userEvent.setup();
+    render(<AdminUsersBlock users={USERS} />);
+
+    await user.type(screen.getByLabelText("Filter by name or email"), "zzzz");
+    expect(await screen.findByText(/No one matches/)).toBeInTheDocument();
+  });
+
+  it("names each row's action button after its row", () => {
+    render(<AdminUsersBlock users={USERS} />);
+    // Four identical "Actions" buttons say nothing about which row you are on.
+    expect(
+      screen.getByRole("button", { name: "Actions for Ada Lovelace" }),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole("button", { name: "Actions for Grace Hopper" }),
+    ).toBeInTheDocument();
+  });
+
+  it("runs the row actions", async () => {
+    const onEdit = vi.fn();
+    const onRemove = vi.fn();
+    const user = userEvent.setup();
+    render(<AdminUsersBlock users={USERS} onEdit={onEdit} onRemove={onRemove} />);
+
+    await user.click(screen.getByRole("button", { name: "Actions for Ada Lovelace" }));
+    await user.click(await screen.findByRole("menuitem", { name: "Edit member" }));
+    expect(onEdit).toHaveBeenCalledWith(expect.objectContaining({ name: "Ada Lovelace" }));
+
+    await user.click(screen.getByRole("button", { name: "Actions for Grace Hopper" }));
+    await user.click(await screen.findByRole("menuitem", { name: "Remove from team" }));
+    expect(onRemove).toHaveBeenCalledWith(expect.objectContaining({ name: "Grace Hopper" }));
+  });
+
+  it("states each status in words", () => {
+    render(<AdminUsersBlock users={USERS} />);
+    expect(screen.getByText("Suspended")).toBeInTheDocument();
+    expect(screen.getByText("Invited")).toBeInTheDocument();
+  });
+
+  it("sorts by a column", async () => {
+    const user = userEvent.setup();
+    render(<AdminUsersBlock users={USERS} />);
+
+    await user.click(screen.getByRole("button", { name: /User, not sorted/ }));
+    await user.click(await screen.findByRole("menuitem", { name: "Sort descending" }));
+
+    await waitFor(() => {
+      expect(screen.getByRole("columnheader", { name: /User/ })).toHaveAttribute(
+        "aria-sort",
+        "descending",
+      );
+    });
+  });
+
+  it("invites people", async () => {
+    const onInvite = vi.fn();
+    const user = userEvent.setup();
+    render(<AdminUsersBlock users={USERS} onInvite={onInvite} />);
+
+    await user.click(screen.getByRole("button", { name: "Invite people" }));
+    expect(onInvite).toHaveBeenCalledTimes(1);
+  });
+
+  it("has no accessibility violations", async () => {
+    const { container } = render(<AdminUsersBlock users={USERS} />);
+    await expectNoA11yViolations(container);
+  });
+});

package/src/blocks/admin-users/admin-users.tsx

@@ -0,0 +1,251 @@
+"use client";
+
+import {
+  columnVisibilityFeature,
+  createPaginatedRowModel,
+  createSortedRowModel,
+  rowPaginationFeature,
+  rowSortingFeature,
+  tableFeatures,
+  useTable,
+} from "@tanstack/react-table";
+import { useMemo, useState } from "react";
+
+import { Avatar, AvatarFallback } from "@/components/avatar";
+import { Badge } from "@/components/badge";
+import { Button } from "@/components/button";
+import {
+  DataTable,
+  DataTableColumnHeader,
+  DataTablePagination,
+  DataTableViewOptions,
+} from "@/components/data-table";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@/components/dropdown-menu";
+import { EmptyState, EmptyStateDescription, EmptyStateTitle } from "@/components/empty-state";
+import { Input } from "@/components/input";
+import { Label } from "@/components/label";
+import { cn } from "@/lib/utils";
+
+/**
+ * A user administration table.
+ *
+ * The filter is the part worth reading. Results change as you type, which for
+ * a screen reader user is a change they never asked for and cannot see — so the
+ * row count is announced politely, and the search input is a labelled control
+ * rather than a placeholder-only box.
+ */
+
+export interface AdminUser {
+  id: string;
+  name: string;
+  email: string;
+  role: "Owner" | "Admin" | "Member" | "Viewer";
+  status: "Active" | "Invited" | "Suspended";
+  lastActive: string;
+}
+
+export interface AdminUsersBlockProps {
+  users: AdminUser[];
+  onInvite?: () => void;
+  onEdit?: (user: AdminUser) => void;
+  onRemove?: (user: AdminUser) => void;
+  className?: string;
+}
+
+const features = tableFeatures({
+  rowSortingFeature,
+  rowPaginationFeature,
+  columnVisibilityFeature,
+  sortedRowModel: createSortedRowModel(),
+  paginatedRowModel: createPaginatedRowModel(),
+});
+
+function initials(name: string): string {
+  return name
+    .split(" ")
+    .map((part) => part[0] ?? "")
+    .slice(0, 2)
+    .join("")
+    .toUpperCase();
+}
+
+export function AdminUsersBlock({
+  users,
+  onInvite,
+  onEdit,
+  onRemove,
+  className,
+}: AdminUsersBlockProps) {
+  const [query, setQuery] = useState("");
+
+  // Filtered here rather than through the table's filtering feature, so the
+  // block stays usable without wiring that feature up.
+  const filtered = useMemo(() => {
+    const needle = query.trim().toLowerCase();
+    if (!needle) return users;
+    return users.filter(
+      (user) =>
+        user.name.toLowerCase().includes(needle) || user.email.toLowerCase().includes(needle),
+    );
+  }, [users, query]);
+
+  const table = useTable({
+    features,
+    data: filtered,
+    initialState: { pagination: { pageIndex: 0, pageSize: 10 } },
+    columns: [
+      {
+        accessorKey: "name",
+        header: ({ column }) => <DataTableColumnHeader column={column} title="User" />,
+        cell: ({ row }) => (
+          <div className="flex items-center gap-3">
+            <Avatar size="sm">
+              <AvatarFallback>{initials(row.original.name)}</AvatarFallback>
+            </Avatar>
+            <div className="min-w-0">
+              <p className="truncate text-sm font-medium">{row.original.name}</p>
+              <p className="truncate text-xs text-muted-foreground">{row.original.email}</p>
+            </div>
+          </div>
+        ),
+      },
+      {
+        accessorKey: "role",
+        header: ({ column }) => <DataTableColumnHeader column={column} title="Role" />,
+      },
+      {
+        accessorKey: "status",
+        header: ({ column }) => <DataTableColumnHeader column={column} title="Status" />,
+        cell: ({ row }) => (
+          <Badge
+            size="sm"
+            variant={
+              row.original.status === "Active"
+                ? "success"
+                : row.original.status === "Suspended"
+                  ? "destructive"
+                  : "secondary"
+            }
+          >
+            {row.original.status}
+          </Badge>
+        ),
+      },
+      {
+        accessorKey: "lastActive",
+        header: ({ column }) => <DataTableColumnHeader column={column} title="Last active" />,
+        cell: ({ row }) => (
+          <span className="text-sm text-muted-foreground">{row.original.lastActive}</span>
+        ),
+      },
+      {
+        id: "actions",
+        // Not an empty header: a th with no text is a column a screen reader
+        // cannot name. Hidden visually, present in the table semantics.
+        header: () => <span className="sr-only">Actions</span>,
+        enableSorting: false,
+        cell: ({ row }) => (
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <Button
+                variant="ghost"
+                size="icon-sm"
+                // Named per row: four identical "Actions" buttons tell a screen
+                // reader user nothing about which row they are on.
+                aria-label={`Actions for ${row.original.name}`}
+              >
+                <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
+                  <circle cx="12" cy="5" r="1.5" fill="currentColor" />
+                  <circle cx="12" cy="12" r="1.5" fill="currentColor" />
+                  <circle cx="12" cy="19" r="1.5" fill="currentColor" />
+                </svg>
+              </Button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent align="end">
+              <DropdownMenuLabel>{row.original.name}</DropdownMenuLabel>
+              <DropdownMenuSeparator />
+              <DropdownMenuItem
+                onSelect={() => {
+                  onEdit?.(row.original);
+                }}
+              >
+                Edit member
+              </DropdownMenuItem>
+              <DropdownMenuItem
+                variant="destructive"
+                onSelect={() => {
+                  onRemove?.(row.original);
+                }}
+              >
+                Remove from team
+              </DropdownMenuItem>
+            </DropdownMenuContent>
+          </DropdownMenu>
+        ),
+      },
+    ],
+  });
+
+  return (
+    <div className={cn("flex flex-col gap-4", className)}>
+      <div className="flex flex-wrap items-end justify-between gap-3">
+        <div>
+          <h1 className="text-xl font-semibold tracking-tight">Team members</h1>
+          <p className="mt-1 text-sm text-muted-foreground">
+            {users.length} {users.length === 1 ? "person" : "people"} in this workspace.
+          </p>
+        </div>
+        <Button onClick={onInvite}>Invite people</Button>
+      </div>
+
+      <div className="flex flex-wrap items-center gap-2">
+        <div className="grid flex-1 gap-1.5 sm:max-w-xs">
+          {/* A real label, not a placeholder: placeholders vanish as soon as
+              anyone types, taking the field's name with them. */}
+          <Label htmlFor="user-filter" className="sr-only">
+            Filter by name or email
+          </Label>
+          <Input
+            id="user-filter"
+            inputSize="sm"
+            type="search"
+            placeholder="Filter by name or email…"
+            value={query}
+            onChange={(event) => {
+              setQuery(event.target.value);
+            }}
+          />
+        </div>
+        <DataTableViewOptions table={table} />
+      </div>
+
+      {/* Filtering changes the results without the user asking, so the count is
+          announced. Polite, so it waits for a pause in typing. */}
+      <p aria-live="polite" className="sr-only">
+        {filtered.length} {filtered.length === 1 ? "person" : "people"} match the filter.
+      </p>
+
+      <DataTable
+        table={table}
+        aria-label="Team members"
+        empty={
+          <EmptyState size="sm">
+            <EmptyStateTitle>No one matches “{query}”</EmptyStateTitle>
+            <EmptyStateDescription>
+              Try a different name or email address.
+            </EmptyStateDescription>
+          </EmptyState>
+        }
+      />
+
+      <DataTablePagination table={table} pageSizes={[10, 25, 50]} />
+    </div>
+  );
+}

package/src/blocks/admin-users/index.ts

@@ -0,0 +1 @@
+export { AdminUsersBlock, type AdminUser, type AdminUsersBlockProps } from "./admin-users";

package/src/blocks/admin-users/meta.ts

@@ -0,0 +1,27 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "admin-users",
+  kind: "block",
+  title: "Admin — users",
+  description: "A team administration table with filtering, sorting and per-row actions.",
+  category: "data",
+  status: "stable",
+  dependencies: ["@tanstack/react-table"],
+  registryDependencies: [
+    "avatar",
+    "badge",
+    "button",
+    "data-table",
+    "dropdown-menu",
+    "empty-state",
+    "input",
+    "label",
+  ],
+  files: ["admin-users.tsx"],
+  a11y:
+    "Filtering changes the results without the user asking, so the matching count is announced " +
+    "politely. The filter has a real label rather than only a placeholder, which disappears the " +
+    "moment anyone types. Each row's action button is named after its row — four identical " +
+    '"Actions" buttons say nothing about which row you are on.',
+});