@tailor-platform/app-shell 1.15.0 → 1.16.0

package/skills/app-shell-patterns/references/api/guards/hidden.md

@@ -0,0 +1,202 @@
+---
+title: hidden
+description: Guard function that denies access and returns 404 Not Found
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/guards/hidden.docs.outline.md — do not edit by hand. -->
+
+# hidden
+
+Returns a guard result that denies access and makes the route return 404 Not Found. The route is also hidden from navigation and search.
+
+## Signature
+
+```typescript
+function hidden(): GuardResult;
+```
+
+## Return Type
+
+```typescript
+{
+  type: "hidden";
+}
+```
+
+## Usage
+
+```typescript
+import { hidden, type Guard } from "@tailor-platform/app-shell";
+
+const denyAccess: Guard = () => {
+  return hidden();
+};
+```
+
+## When to Use
+
+Use `hidden()` when:
+
+- ✅ Access should be denied
+- ✅ User doesn't have required permissions
+- ✅ You want to hide the page completely (404)
+- ✅ Feature is not available for current user
+
+## Effects
+
+When `hidden()` is returned:
+
+- 🚫 Route returns **404 Not Found**
+- 🚫 Hidden from **sidebar navigation**
+- 🚫 Hidden from **CommandPalette** search
+- 🚫 Not shown in **breadcrumbs**
+- 🚫 Direct URL access returns 404
+
+## Examples
+
+### Deny All Access
+
+```typescript
+const denyAll: Guard = () => hidden();
+```
+
+### Role-Based Hiding
+
+```typescript
+const adminOnly: Guard = ({ context }) => {
+  if (context.currentUser?.role !== "admin") {
+    return hidden(); // Non-admins see 404
+  }
+  return pass();
+};
+```
+
+### Permission-Based Hiding
+
+```typescript
+const requirePermission =
+  (perm: string): Guard =>
+  ({ context }) => {
+    if (!context.permissions.includes(perm)) {
+      return hidden(); // No permission → 404
+    }
+    return pass();
+  };
+```
+
+### Feature Flag
+
+```typescript
+const requireBetaFeature: Guard = ({ context }) => {
+  if (!context.featureFlags?.beta) {
+    return hidden(); // Feature disabled → 404
+  }
+  return pass();
+};
+```
+
+### Subscription Tier
+
+```typescript
+const premiumOnly: Guard = ({ context }) => {
+  if (context.currentUser?.plan !== "premium") {
+    return hidden(); // Free users see 404
+  }
+  return pass();
+};
+```
+
+### Conditional Hiding
+
+```typescript
+const conditionalHide: Guard = ({ context }) => {
+  // Multiple conditions
+  if (!context.currentUser || context.currentUser.suspended || !context.currentUser.emailVerified) {
+    return hidden();
+  }
+  return pass();
+};
+```
+
+### Async Permission Check
+
+```typescript
+const asyncHide: Guard = async ({ context }) => {
+  const allowed = await fetch("/api/check-access");
+  if (!allowed) {
+    return hidden();
+  }
+  return pass();
+};
+```
+
+## vs redirectTo()
+
+| Aspect         | hidden()             | redirectTo()             |
+| -------------- | -------------------- | ------------------------ |
+| **Result**     | 404 Not Found        | Redirect to page         |
+| **URL**        | Stays same           | Changes to new URL       |
+| **Navigation** | Hidden               | Not affected             |
+| **Use Case**   | Deny access silently | Send to login/error page |
+
+### Example: When to Use Each
+
+```typescript
+// Use hidden() - Silently deny access
+const adminFeature: Guard = ({ context }) => {
+  if (!isAdmin(context)) {
+    return hidden(); // Non-admins don't even see this exists
+  }
+  return pass();
+};
+
+// Use redirectTo() - Explicitly redirect
+const requireAuth: Guard = ({ context }) => {
+  if (!context.currentUser) {
+    return redirectTo("/login"); // Unauthenticated users go to login
+  }
+  return pass();
+};
+```
+
+## Navigation Impact
+
+```typescript
+// Before guard (user is not admin):
+Sidebar:
+› Dashboard
+› Products
+› Admin Panel  ← Visible
+
+// After guard returns hidden():
+Sidebar:
+› Dashboard
+› Products
+               ← Admin Panel disappeared
+
+// Direct URL access: /admin
+// Result: 404 Not Found
+```
+
+## WithGuard Component
+
+`hidden()` works with `WithGuard` to hide UI elements:
+
+```typescript
+import { WithGuard, hidden, pass } from "@tailor-platform/app-shell";
+
+const isAdmin = ({ context }) =>
+  context.currentUser?.role === "admin" ? pass() : hidden();
+
+<WithGuard guards={[isAdmin]}>
+  <Button>Delete All Users</Button>
+</WithGuard>
+// Non-admins: button doesn't render
+```
+
+## Related
+
+- [pass()](./pass.md) - Allow access and continue
+- [redirectTo()](./redirect-to.md) - Redirect to another page
+- [Guards Overview](./overview.md) - Complete guard system guide
+- [WithGuard Component](../../components/with-guard.md) - Component-level guards

package/skills/app-shell-patterns/references/api/guards/overview.md

@@ -0,0 +1,354 @@
+---
+title: Guards Overview
+description: Access control system for routes and components using guard functions
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/guards/overview.docs.outline.md — do not edit by hand. -->
+
+# Guards Overview
+
+Guards are functions that control access to routes and UI elements in AppShell. They provide a flexible, composable way to implement permission-based and role-based access control.
+
+## How Guards Work
+
+Guards are executed sequentially and can return one of three results:
+
+- **`pass()`** - Allow access, continue to next guard
+- **`hidden()`** - Deny access, return 404
+- **`redirectTo(path)`** - Redirect to another page
+
+If any guard returns `hidden()` or `redirectTo()`, execution stops immediately.
+
+## Guard Function Signature
+
+```typescript
+type Guard = (ctx: GuardContext) => GuardResult | Promise<GuardResult>;
+
+type GuardContext = {
+  context: ContextData; // Your custom context from AppShell
+};
+
+type GuardResult = { type: "pass" } | { type: "hidden" } | { type: "redirect"; to: string };
+```
+
+## Guard Functions
+
+### pass()
+
+Allows access and continues to the next guard.
+
+```typescript
+import { pass } from "@tailor-platform/app-shell";
+
+const allowAll: Guard = () => pass();
+```
+
+[Full Reference →](./pass.md)
+
+### hidden()
+
+Denies access and shows 404 Not Found.
+
+```typescript
+import { hidden } from "@tailor-platform/app-shell";
+
+const denyAll: Guard = () => hidden();
+```
+
+[Full Reference →](./hidden.md)
+
+### redirectTo(path)
+
+Redirects to another page.
+
+```typescript
+import { redirectTo } from "@tailor-platform/app-shell";
+
+const redirectToLogin: Guard = () => redirectTo("/login");
+```
+
+[Full Reference →](./redirect-to.md)
+
+## Usage Locations
+
+### Route-Level Guards
+
+Applied to modules and resources:
+
+```typescript
+import { defineModule, pass, hidden } from "@tailor-platform/app-shell";
+
+const adminModule = defineModule({
+  path: "admin",
+  component: AdminPage,
+  guards: [
+    ({ context }) => {
+      return context.currentUser?.role === "admin" ? pass() : hidden();
+    },
+  ],
+});
+```
+
+### Component-Level Guards
+
+Applied to UI elements with `WithGuard`:
+
+```typescript
+import { WithGuard, pass, hidden } from "@tailor-platform/app-shell";
+
+const isAdmin = ({ context }) =>
+  context.currentUser?.role === "admin" ? pass() : hidden();
+
+<WithGuard guards={[isAdmin]}>
+  <Button>Delete All</Button>
+</WithGuard>
+```
+
+## Context Data
+
+Guards receive context data from AppShell:
+
+```typescript
+// Define your context type
+declare module "@tailor-platform/app-shell" {
+  interface AppShellRegister {
+    contextData: {
+      currentUser: User | null;
+      permissions: string[];
+      featureFlags: FeatureFlags;
+    };
+  }
+}
+
+// Pass context to AppShell
+<AppShell
+  modules={modules}
+  contextData={{
+    currentUser,
+    permissions,
+    featureFlags,
+  }}
+>
+  {/* ... */}
+</AppShell>
+
+// Access in guards
+const guard: Guard = ({ context }) => {
+  // context is fully typed!
+  if (context.currentUser) {
+    return pass();
+  }
+  return hidden();
+};
+```
+
+## Common Patterns
+
+### Authentication Check
+
+```typescript
+const requireAuth: Guard = ({ context }) => {
+  if (!context.currentUser) {
+    return redirectTo("/login");
+  }
+  return pass();
+};
+```
+
+### Role-Based Access
+
+```typescript
+const requireAdmin: Guard = ({ context }) => {
+  if (context.currentUser?.role !== "admin") {
+    return hidden();
+  }
+  return pass();
+};
+```
+
+### Permission-Based Access
+
+```typescript
+const requirePermission =
+  (permission: string): Guard =>
+  ({ context }) => {
+    if (!context.permissions.includes(permission)) {
+      return hidden();
+    }
+    return pass();
+  };
+
+// Usage
+guards: [requirePermission("users:delete")];
+```
+
+### Feature Flags
+
+```typescript
+const requireFeature =
+  (flag: string): Guard =>
+  ({ context }) => {
+    if (!context.featureFlags[flag]) {
+      return hidden();
+    }
+    return pass();
+  };
+```
+
+### Async Permission Check
+
+```typescript
+const checkApiPermission: Guard = async ({ context }) => {
+  const response = await fetch("/api/permissions/admin");
+  const { allowed } = await response.json();
+  return allowed ? pass() : hidden();
+};
+```
+
+### Multiple Guards (AND logic)
+
+```typescript
+const guards = [requireAuth, requireAdmin, requireFeature("beta")];
+
+// All must pass() for access to be granted
+defineModule({
+  path: "admin",
+  guards: guards,
+});
+```
+
+### Reusable Guard Library
+
+```typescript
+// guards.ts
+export const requireAuth: Guard = ({ context }) => {
+  return context.currentUser ? pass() : redirectTo("/login");
+};
+
+export const requireRole =
+  (role: string): Guard =>
+  ({ context }) => {
+    return context.currentUser?.role === role ? pass() : hidden();
+  };
+
+export const requirePermission =
+  (perm: string): Guard =>
+  ({ context }) => {
+    return context.permissions.includes(perm) ? pass() : hidden();
+  };
+
+// Usage across application
+import { requireAuth, requireRole } from "./guards";
+
+defineModule({
+  path: "admin",
+  guards: [requireAuth, requireRole("admin")],
+});
+```
+
+## Guard Execution Order
+
+Guards are executed sequentially in the order they're defined:
+
+```typescript
+guards: [guardA, guardB, guardC];
+
+// Execution:
+// 1. guardA runs → if not pass(), stop
+// 2. guardB runs → if not pass(), stop
+// 3. guardC runs → if not pass(), stop
+// 4. All passed → grant access
+```
+
+## Navigation Behavior
+
+When guards return `hidden()`:
+
+- Route returns 404 Not Found
+- Item hidden from sidebar navigation
+- Item hidden from CommandPalette
+- Breadcrumbs don't show the page
+
+When guards return `redirectTo()`:
+
+- User is redirected immediately
+- Original URL is not accessible
+- Useful for login flows
+
+## Best Practices
+
+### Do:
+
+- ✅ Keep guards simple and focused
+- ✅ Reuse guards across routes and components
+- ✅ Use descriptive names (requireAuth, not guard1)
+- ✅ Return quickly for better performance
+- ✅ Cache expensive checks when possible
+
+### Don't:
+
+- ❌ Make guards too complex (extract logic)
+- ❌ Have side effects in guards (logging OK)
+- ❌ Duplicate guard logic (DRY principle)
+- ❌ Forget to handle async errors
+- ❌ Use redirectTo() in WithGuard (not supported)
+
+## TypeScript
+
+Full type safety:
+
+```typescript
+import { type Guard, type GuardContext, type GuardResult } from "@tailor-platform/app-shell";
+
+const myGuard: Guard = (ctx: GuardContext): GuardResult => {
+  // Fully typed context
+  return pass();
+};
+
+// Async guard
+const asyncGuard: Guard = async (ctx): Promise<GuardResult> => {
+  await someAsyncCheck();
+  return pass();
+};
+```
+
+## Performance
+
+### Sync Guards (Fast)
+
+```typescript
+const isAdmin: Guard = ({ context }) => {
+  return context.currentUser?.role === "admin" ? pass() : hidden();
+};
+// ~0ms - Instant
+```
+
+### Async Guards (Slower)
+
+```typescript
+const checkPermission: Guard = async ({ context }) => {
+  const allowed = await fetch("/api/check");
+  return allowed ? pass() : hidden();
+};
+// ~50-200ms - Network request
+```
+
+**Tip:** Prefer sync guards when possible. Cache API results in context data.
+
+## Comparison: Route vs Component Guards
+
+| Aspect                    | Route Guards                | Component Guards (WithGuard) |
+| ------------------------- | --------------------------- | ---------------------------- |
+| **Location**              | defineModule/defineResource | WithGuard component          |
+| **Supports pass()**       | ✅ Yes                      | ✅ Yes                       |
+| **Supports hidden()**     | ✅ Yes                      | ✅ Yes                       |
+| **Supports redirectTo()** | ✅ Yes                      | ❌ No                        |
+| **Execution**             | Before route loads          | During render                |
+| **Use Case**              | Page access control         | UI element visibility        |
+
+## Related
+
+- [pass()](./pass.md) - Allow access guard function
+- [hidden()](./hidden.md) - Hide/deny access guard function
+- [redirectTo()](./redirect-to.md) - Redirect guard function
+- [WithGuard Component](../../components/with-guard.md) - Component-level guards

package/skills/app-shell-patterns/references/api/guards/pass.md

@@ -0,0 +1,129 @@
+---
+title: pass
+description: Guard function that allows access and continues to the next guard
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/guards/pass.docs.outline.md — do not edit by hand. -->
+
+# pass
+
+Returns a guard result that allows access and continues to the next guard in the chain.
+
+## Signature
+
+```typescript
+function pass(): GuardResult;
+```
+
+## Return Type
+
+```typescript
+{
+  type: "pass";
+}
+```
+
+## Usage
+
+```typescript
+import { pass, type Guard } from "@tailor-platform/app-shell";
+
+const allowAccess: Guard = () => {
+  return pass();
+};
+```
+
+## When to Use
+
+Use `pass()` when:
+
+- ✅ Access should be granted
+- ✅ User meets the required conditions
+- ✅ You want to continue to the next guard
+
+## Examples
+
+### Always Allow
+
+```typescript
+const allowAll: Guard = () => pass();
+```
+
+### Conditional Access
+
+```typescript
+const requireAuth: Guard = ({ context }) => {
+  if (context.currentUser) {
+    return pass(); // User is authenticated
+  }
+  return redirectTo("/login");
+};
+```
+
+### Role Check
+
+```typescript
+const requireAdmin: Guard = ({ context }) => {
+  if (context.currentUser?.role === "admin") {
+    return pass(); // User is admin
+  }
+  return hidden();
+};
+```
+
+### Permission Check
+
+```typescript
+const requirePermission =
+  (perm: string): Guard =>
+  ({ context }) => {
+    if (context.permissions.includes(perm)) {
+      return pass(); // User has permission
+    }
+    return hidden();
+  };
+```
+
+### Multiple Conditions
+
+```typescript
+const complexGuard: Guard = ({ context }) => {
+  // Check multiple conditions
+  if (context.currentUser && context.currentUser.active && !context.currentUser.suspended) {
+    return pass(); // All conditions met
+  }
+  return hidden();
+};
+```
+
+### Async Guard
+
+```typescript
+const asyncGuard: Guard = async ({ context }) => {
+  const isValid = await validateToken(context.token);
+  if (isValid) {
+    return pass();
+  }
+  return redirectTo("/login");
+};
+```
+
+## Guard Chaining
+
+When `pass()` is returned, the next guard in the array executes:
+
+```typescript
+guards: [
+  guardA, // Returns pass() → Continue to guardB
+  guardB, // Returns pass() → Continue to guardC
+  guardC, // Returns pass() → Grant access
+];
+```
+
+If all guards return `pass()`, access is granted.
+
+## Related
+
+- [hidden()](./hidden.md) - Deny access and return 404
+- [redirectTo()](./redirect-to.md) - Redirect to another page
+- [Guards Overview](./overview.md) - Complete guard system guide