@checkstack/ui 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # @checkstack/ui
 
+## 0.2.0
+
+### Minor Changes
+
+- 9faec1f: # Unified AccessRule Terminology Refactoring
+
+  This release completes a comprehensive terminology refactoring from "permission" to "accessRule" across the entire codebase, establishing a consistent and modern access control vocabulary.
+
+  ## Changes
+
+  ### Core Infrastructure (`@checkstack/common`)
+
+  - Introduced `AccessRule` interface as the primary access control type
+  - Added `accessPair()` helper for creating read/manage access rule pairs
+  - Added `access()` builder for individual access rules
+  - Replaced `Permission` type with `AccessRule` throughout
+
+  ### API Changes
+
+  - `env.registerPermissions()` → `env.registerAccessRules()`
+  - `meta.permissions` → `meta.access` in RPC contracts
+  - `usePermission()` → `useAccess()` in frontend hooks
+  - Route `permission:` field → `accessRule:` field
+
+  ### UI Changes
+
+  - "Roles & Permissions" tab → "Roles & Access Rules"
+  - "You don't have permission..." → "You don't have access..."
+  - All permission-related UI text updated
+
+  ### Documentation & Templates
+
+  - Updated 18 documentation files with AccessRule terminology
+  - Updated 7 scaffolding templates with `accessPair()` pattern
+  - All code examples use new AccessRule API
+
+  ## Migration Guide
+
+  ### Backend Plugins
+
+  ```diff
+  - import { permissionList } from "./permissions";
+  - env.registerPermissions(permissionList);
+  + import { accessRules } from "./access";
+  + env.registerAccessRules(accessRules);
+  ```
+
+  ### RPC Contracts
+
+  ```diff
+  - .meta({ userType: "user", permissions: [permissions.read.id] })
+  + .meta({ userType: "user", access: [access.read] })
+  ```
+
+  ### Frontend Hooks
+
+  ```diff
+  - const canRead = accessApi.usePermission(permissions.read.id);
+  + const canRead = accessApi.useAccess(access.read);
+  ```
+
+  ### Routes
+
+  ```diff
+  - permission: permissions.entityRead.id,
+  + accessRule: access.read,
+  ```
+
+### Patch Changes
+
+- Updated dependencies [9faec1f]
+- Updated dependencies [f533141]
+  - @checkstack/common@0.2.0
+  - @checkstack/frontend-api@0.1.0
+
 ## 0.1.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/ui",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "src/index.ts",
   "dependencies": {

package/src/components/{PermissionDenied.tsx → AccessDenied.tsx}

@@ -3,13 +3,10 @@ import { ShieldAlert } from "lucide-react";
 import { Card, CardHeader, CardTitle, CardContent } from "./Card";
 import { cn } from "../utils";
 
-export const PermissionDenied: React.FC<{
+export const AccessDenied: React.FC<{
   message?: string;
   className?: string;
-}> = ({
-  message = "You do not have permission to view this page.",
-  className,
-}) => {
+}> = ({ message = "You do not have access to this page.", className }) => {
   return (
     <div
       className={cn(

package/src/components/AccessGate.tsx

@@ -0,0 +1,97 @@
+import React from "react";
+import { AccessDenied } from "./AccessDenied";
+import { LoadingSpinner } from "./LoadingSpinner";
+
+/**
+ * Props for the AccessGate component.
+ */
+export interface AccessGateProps {
+  /**
+   * The access rule ID to check for access.
+   */
+  accessRuleId: string;
+  /**
+   * Content to render when access is granted.
+   */
+  children: React.ReactNode;
+  /**
+   * Custom fallback to render when access is denied.
+   * If not provided and showDenied is false, renders nothing.
+   */
+  fallback?: React.ReactNode;
+  /**
+   * If true, shows a AccessDenied component when access is denied.
+   * Useful for entire page sections. Overridden by fallback if provided.
+   */
+  showDenied?: boolean;
+  /**
+   * Custom message to show in the AccessDenied component.
+   */
+  deniedMessage?: string;
+  /**
+   * Hook to check access. Must be provided by the consumer.
+   * This allows the component to be used without depending on auth-frontend directly.
+   */
+  useAccess: (accessRuleId: string) => { loading: boolean; allowed: boolean };
+}
+
+/**
+ * Conditionally renders children based on whether the user has a required access rule.
+ *
+ * @example
+ * // Hide content if access denied
+ * <AccessGate accessRuleId="catalog.manage" useAccess={accessApi.useAccess}>
+ *   <ManageButton />
+ * </AccessGate>
+ *
+ * @example
+ * // Show access denied message
+ * <AccessGate
+ *   accessRuleId="catalog.read"
+ *   useAccess={accessApi.useAccess}
+ *   showDenied
+ *   deniedMessage="You don't have access to view the catalog."
+ * >
+ *   <CatalogList />
+ * </AccessGate>
+ *
+ * @example
+ * // Custom fallback
+ * <AccessGate
+ *   accessRuleId="admin.manage"
+ *   useAccess={accessApi.useAccess}
+ *   fallback={<p>Admin access required</p>}
+ * >
+ *   <AdminPanel />
+ * </AccessGate>
+ */
+export const AccessGate: React.FC<AccessGateProps> = ({
+  accessRuleId,
+  children,
+  fallback,
+  showDenied = false,
+  deniedMessage,
+  useAccess,
+}) => {
+  const { loading, allowed } = useAccess(accessRuleId);
+
+  if (loading) {
+    return <LoadingSpinner size="sm" />;
+  }
+
+  if (!allowed) {
+    if (fallback) {
+      return <>{fallback}</>;
+    }
+    if (showDenied) {
+      return (
+        <AccessDenied
+          message={deniedMessage ?? `You don't have access: ${accessRuleId}`}
+        />
+      );
+    }
+    return <></>;
+  }
+
+  return <>{children}</>;
+};

package/src/components/NavItem.tsx

@@ -2,13 +2,15 @@ import React, { useState, useRef, useEffect } from "react";
 import { NavLink } from "react-router-dom";
 import { ChevronDown } from "lucide-react";
 import { cn } from "../utils";
-import { useApi, permissionApiRef } from "@checkstack/frontend-api";
+import { useApi, accessApiRef } from "@checkstack/frontend-api";
+import type { AccessRule } from "@checkstack/common";
 
 export interface NavItemProps {
   to?: string;
   label: string;
   icon?: React.ReactNode;
-  permission?: string;
+  /** Access rule to check - if not provided, always shows */
+  accessRule?: AccessRule;
   children?: React.ReactNode;
   className?: string;
 }
@@ -17,7 +19,7 @@ export const NavItem: React.FC<NavItemProps> = ({
   to,
   label,
   icon,
-  permission,
+  accessRule,
   children,
   className,
 }) => {
@@ -25,11 +27,17 @@ export const NavItem: React.FC<NavItemProps> = ({
   const containerRef = useRef<HTMLDivElement>(null);
 
   // Always call hooks at top level
-  // We assume permissionApi is available if we use it. Safe fallback?
-  // ApiProvider guarantees it if registered. App.tsx registers a default.
-  const permissionApi = useApi(permissionApiRef);
-  const { allowed, loading } = permissionApi.usePermission(permission || "");
-  const hasAccess = permission ? allowed : true;
+  const accessApi = useApi(accessApiRef);
+
+  // Create a dummy access rule for when accessRule is undefined
+  const dummyRule: AccessRule = {
+    id: "",
+    resource: "",
+    level: "read",
+    description: "",
+  };
+  const { allowed, loading } = accessApi.useAccess(accessRule ?? dummyRule);
+  const hasAccess = accessRule ? allowed : true;
 
   // Handle click outside for dropdown
   useEffect(() => {

package/src/components/PageLayout.tsx

@@ -4,7 +4,7 @@ import {
   PageHeader,
   PageContent,
   LoadingSpinner,
-  PermissionDenied,
+  AccessDenied,
 } from "..";
 
 interface PageLayoutProps {
@@ -39,7 +39,7 @@ export const PageLayout: React.FC<PageLayoutProps> = ({
 }) => {
   // If loading is explicitly true, show loading state
   // If loading is undefined and allowed is false, also show loading state
-  // (this prevents "Access Denied" flash when permissions are still being fetched)
+  // (this prevents "Access Denied" flash when access rules are still being fetched)
   const isLoading =
     loading === true || (loading === undefined && allowed === false);
 
@@ -56,13 +56,13 @@ export const PageLayout: React.FC<PageLayoutProps> = ({
     );
   }
 
-  // Only show permission denied when loading is explicitly false and allowed is false
+  // Only show access denied when loading is explicitly false and allowed is false
   if (allowed === false) {
     return (
       <Page>
         <PageHeader title={title} subtitle={subtitle} actions={actions} />
         <PageContent>
-          <PermissionDenied />
+          <AccessDenied />
         </PageContent>
       </Page>
     );

package/src/index.ts

@@ -3,8 +3,8 @@ export * from "./components/Input";
 export * from "./components/Card";
 export * from "./components/Label";
 export * from "./components/NavItem";
-export * from "./components/PermissionDenied";
-export * from "./components/PermissionGate";
+export * from "./components/AccessDenied";
+export * from "./components/AccessGate";
 export * from "./components/SectionHeader";
 export * from "./components/StatusCard";
 export * from "./components/EmptyState";

package/src/components/PermissionGate.tsx

@@ -1,97 +0,0 @@
-import React from "react";
-import { PermissionDenied } from "./PermissionDenied";
-import { LoadingSpinner } from "./LoadingSpinner";
-
-/**
- * Props for the PermissionGate component.
- */
-export interface PermissionGateProps {
-  /**
-   * The permission ID to check for access.
-   */
-  permission: string;
-  /**
-   * Content to render when permission is granted.
-   */
-  children: React.ReactNode;
-  /**
-   * Custom fallback to render when permission is denied.
-   * If not provided and showDenied is false, renders nothing.
-   */
-  fallback?: React.ReactNode;
-  /**
-   * If true, shows a PermissionDenied component when access is denied.
-   * Useful for entire page sections. Overridden by fallback if provided.
-   */
-  showDenied?: boolean;
-  /**
-   * Custom message to show in the PermissionDenied component.
-   */
-  deniedMessage?: string;
-  /**
-   * Hook to check permissions. Must be provided by the consumer.
-   * This allows the component to be used without depending on auth-frontend directly.
-   */
-  usePermission: (permission: string) => { loading: boolean; allowed: boolean };
-}
-
-/**
- * Conditionally renders children based on whether the user has a required permission.
- *
- * @example
- * // Hide content if permission denied
- * <PermissionGate permission="catalog.manage" usePermission={permissionApi.usePermission}>
- *   <ManageButton />
- * </PermissionGate>
- *
- * @example
- * // Show permission denied message
- * <PermissionGate
- *   permission="catalog.read"
- *   usePermission={permissionApi.usePermission}
- *   showDenied
- *   deniedMessage="You don't have access to view the catalog."
- * >
- *   <CatalogList />
- * </PermissionGate>
- *
- * @example
- * // Custom fallback
- * <PermissionGate
- *   permission="admin.manage"
- *   usePermission={permissionApi.usePermission}
- *   fallback={<p>Admin access required</p>}
- * >
- *   <AdminPanel />
- * </PermissionGate>
- */
-export const PermissionGate: React.FC<PermissionGateProps> = ({
-  permission,
-  children,
-  fallback,
-  showDenied = false,
-  deniedMessage,
-  usePermission,
-}) => {
-  const { loading, allowed } = usePermission(permission);
-
-  if (loading) {
-    return <LoadingSpinner size="sm" />;
-  }
-
-  if (!allowed) {
-    if (fallback) {
-      return <>{fallback}</>;
-    }
-    if (showDenied) {
-      return (
-        <PermissionDenied
-          message={deniedMessage ?? `You don't have permission: ${permission}`}
-        />
-      );
-    }
-    return <></>;
-  }
-
-  return <>{children}</>;
-};