@tailor-platform/app-shell 1.14.0 → 1.16.0

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

@@ -0,0 +1,307 @@
+---
+title: redirectTo
+description: Guard function that redirects to another page
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/guards/redirect-to.docs.outline.md — do not edit by hand. -->
+
+# redirectTo
+
+Returns a guard result that redirects the user to a different URL. Used primarily for authentication flows and access control redirection.
+
+## Signature
+
+```typescript
+function redirectTo(to: string): GuardResult;
+```
+
+## Parameters
+
+### `to`
+
+- **Type:** `string`
+- **Required:** Yes
+- **Description:** Target URL path to redirect to
+
+## Return Type
+
+```typescript
+{
+  type: "redirect";
+  to: string;
+}
+```
+
+## Usage
+
+```typescript
+import { redirectTo, type Guard } from "@tailor-platform/app-shell";
+
+const redirectToLogin: Guard = () => {
+  return redirectTo("/login");
+};
+```
+
+## When to Use
+
+Use `redirectTo()` when:
+
+- ✅ User needs authentication (redirect to login)
+- ✅ User needs to complete setup (redirect to onboarding)
+- ✅ Access denied but you want to show why (redirect to error page)
+- ✅ You want explicit navigation vs silent denial
+
+## Examples
+
+### Require Authentication
+
+```typescript
+const requireAuth: Guard = ({ context }) => {
+  if (!context.currentUser) {
+    return redirectTo("/login");
+  }
+  return pass();
+};
+```
+
+### Subscription Required
+
+```typescript
+const requirePremium: Guard = ({ context }) => {
+  if (context.currentUser?.plan !== "premium") {
+    return redirectTo("/upgrade");
+  }
+  return pass();
+};
+```
+
+### Complete Profile
+
+```typescript
+const requireProfile: Guard = ({ context }) => {
+  if (!context.currentUser?.profileComplete) {
+    return redirectTo("/complete-profile");
+  }
+  return pass();
+};
+```
+
+### Email Verification
+
+```typescript
+const requireVerifiedEmail: Guard = ({ context }) => {
+  if (!context.currentUser?.emailVerified) {
+    return redirectTo("/verify-email");
+  }
+  return pass();
+};
+```
+
+### Terms Acceptance
+
+```typescript
+const requireTerms: Guard = ({ context }) => {
+  if (!context.currentUser?.termsAccepted) {
+    return redirectTo("/accept-terms");
+  }
+  return pass();
+};
+```
+
+### Role-Based Redirect
+
+```typescript
+const redirectNonAdmins: Guard = ({ context }) => {
+  if (context.currentUser?.role !== "admin") {
+    return redirectTo("/access-denied");
+  }
+  return pass();
+};
+```
+
+### Conditional Redirect
+
+```typescript
+const conditionalRedirect: Guard = ({ context }) => {
+  const user = context.currentUser;
+
+  if (!user) {
+    return redirectTo("/login");
+  }
+
+  if (user.suspended) {
+    return redirectTo("/account-suspended");
+  }
+
+  if (!user.onboardingComplete) {
+    return redirectTo("/onboarding");
+  }
+
+  return pass();
+};
+```
+
+### Async Redirect
+
+```typescript
+const asyncRedirect: Guard = async ({ context }) => {
+  const status = await fetch("/api/user-status");
+  const { active } = await status.json();
+
+  if (!active) {
+    return redirectTo("/reactivate");
+  }
+
+  return pass();
+};
+```
+
+## vs hidden()
+
+| Aspect                | redirectTo()             | hidden()                |
+| --------------------- | ------------------------ | ----------------------- |
+| **Result**            | Redirect to URL          | 404 Not Found           |
+| **User Experience**   | Clear (shows why denied) | Silent (no explanation) |
+| **URL Changes**       | Yes                      | No                      |
+| **Navigation Impact** | No effect                | Hides from navigation   |
+| **Use Case**          | Login flows, errors      | Permission hiding       |
+
+### Example: When to Use Each
+
+```typescript
+// Use redirectTo() - User needs to take action
+const requireAuth: Guard = ({ context }) => {
+  if (!context.currentUser) {
+    return redirectTo("/login"); // Clear: "You need to log in"
+  }
+  return pass();
+};
+
+// Use hidden() - Feature doesn't exist for user
+const adminFeature: Guard = ({ context }) => {
+  if (!isAdmin(context)) {
+    return hidden(); // Silent: User doesn't even know this exists
+  }
+  return pass();
+};
+```
+
+## Redirect Chains
+
+Guards can create redirect chains:
+
+```typescript
+const guards = [
+  // 1. Check authentication
+  ({ context }) => {
+    if (!context.currentUser) {
+      return redirectTo("/login");
+    }
+    return pass();
+  },
+  // 2. Check onboarding (only runs if authenticated)
+  ({ context }) => {
+    if (!context.currentUser?.onboardingComplete) {
+      return redirectTo("/onboarding");
+    }
+    return pass();
+  },
+  // 3. Check permissions (only runs if onboarded)
+  ({ context }) => {
+    if (!context.currentUser?.hasAccess) {
+      return redirectTo("/upgrade");
+    }
+    return pass();
+  },
+];
+```
+
+## Module vs Resource Redirects
+
+### Module-Level
+
+```typescript
+const dashboardModule = defineModule({
+  path: "dashboard",
+  component: DashboardPage,
+  guards: [
+    ({ context }) => {
+      if (!context.currentUser) {
+        return redirectTo("/login");
+      }
+      return pass();
+    },
+  ],
+});
+
+// Accessing /dashboard without auth → Redirects to /login
+```
+
+### Resource-Level
+
+```typescript
+const settingsResource = defineResource({
+  path: "settings",
+  component: SettingsPage,
+  guards: [
+    ({ context }) => {
+      if (!context.currentUser?.emailVerified) {
+        return redirectTo("/verify-email");
+      }
+      return pass();
+    },
+  ],
+});
+
+// Accessing /settings without verified email → Redirects to /verify-email
+```
+
+## Limitations
+
+### Not Supported in WithGuard
+
+`redirectTo()` does **NOT** work with the `WithGuard` component:
+
+```typescript
+// ❌ NOT SUPPORTED
+<WithGuard
+  guards={[
+    () => redirectTo("/login") // This won't work!
+  ]}
+>
+  <Content />
+</WithGuard>
+
+// ✅ Use hidden() with fallback instead
+<WithGuard
+  guards={[() => hidden()]}
+  fallback={<Navigate to="/login" />}
+>
+  <Content />
+</WithGuard>
+```
+
+## Preserving Original URL
+
+To preserve the original URL after redirect:
+
+```typescript
+const requireAuth: Guard = ({ context }) => {
+  if (!context.currentUser) {
+    const currentPath = window.location.pathname;
+    return redirectTo(`/login?redirect=${encodeURIComponent(currentPath)}`);
+  }
+  return pass();
+};
+
+// After login, redirect back:
+// const redirect = searchParams.get('redirect');
+// if (redirect) navigate(redirect);
+```
+
+## Related
+
+- [pass()](./pass.md) - Allow access and continue
+- [hidden()](./hidden.md) - Deny access and return 404
+- [Guards Overview](./overview.md) - Complete guard system guide
+- [WithGuard Component](../../components/with-guard.md) - Component-level guards (doesn't support redirectTo)

package/skills/app-shell-patterns/references/api/router/use-location.md

@@ -0,0 +1,240 @@
+---
+title: useLocation
+description: Hook to access current location object with pathname, search, and state
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/router/use-location.docs.outline.md — do not edit by hand. -->
+
+# useLocation
+
+React Router hook to access the current location object. Re-exported from `react-router` for convenience.
+
+## Signature
+
+```typescript
+const useLocation: () => Location;
+```
+
+## Return Type
+
+```typescript
+interface Location {
+  pathname: string; // Current path: "/products/123"
+  search: string; // Query string: "?sort=name&page=2"
+  hash: string; // Hash: "#details"
+  state: any; // State passed via navigate()
+  key: string; // Unique key for this location
+}
+```
+
+## Usage
+
+### Access Current Path
+
+```typescript
+import { useLocation } from "@tailor-platform/app-shell";
+
+function Breadcrumb() {
+  const location = useLocation();
+
+  return <div>Current path: {location.pathname}</div>;
+}
+```
+
+### Check Active Route
+
+```typescript
+function NavItem({ path, label }: { path: string; label: string }) {
+  const location = useLocation();
+  const isActive = location.pathname === path;
+
+  return (
+    <a
+      href={path}
+      className={isActive ? "active" : ""}
+    >
+      {label}
+    </a>
+  );
+}
+```
+
+### Access Query Parameters
+
+```typescript
+function ProductsList() {
+  const location = useLocation();
+  const searchParams = new URLSearchParams(location.search);
+
+  const sort = searchParams.get("sort"); // "name"
+  const page = searchParams.get("page"); // "2"
+
+  return <div>Sort: {sort}, Page: {page}</div>;
+}
+
+// URL: /products?sort=name&page=2
+```
+
+### Access Navigation State
+
+```typescript
+// Navigate with state
+function ProductsList() {
+  const navigate = useNavigate();
+
+  const selectProduct = (id: string) => {
+    navigate(`/products/${id}`, {
+      state: { from: "list", scrollPosition: window.scrollY },
+    });
+  };
+}
+
+// Access state in target component
+function ProductDetail() {
+  const location = useLocation();
+  const from = location.state?.from;           // "list"
+  const scrollPos = location.state?.scrollPosition; // 450
+
+  return <div>Came from: {from}</div>;
+}
+```
+
+### Track Route Changes
+
+```typescript
+function AnalyticsTracker() {
+  const location = useLocation();
+
+  useEffect(() => {
+    // Track page view
+    analytics.pageView(location.pathname);
+  }, [location.pathname]);
+
+  return null;
+}
+```
+
+### Preserve Query Params on Navigation
+
+```typescript
+function FilterButton({ filter }: { filter: string }) {
+  const location = useLocation();
+  const navigate = useNavigate();
+
+  const applyFilter = () => {
+    const params = new URLSearchParams(location.search);
+    params.set("filter", filter);
+    navigate(`${location.pathname}?${params}`);
+  };
+
+  return <button onClick={applyFilter}>Apply Filter</button>;
+}
+```
+
+## Common Patterns
+
+### Check Prefix Match
+
+```typescript
+function isActiveRoute(pathname: string, prefix: string) {
+  return pathname.startsWith(prefix);
+}
+
+function NavItem({ path }: { path: string }) {
+  const location = useLocation();
+  const isActive = isActiveRoute(location.pathname, path);
+
+  return <a className={isActive ? "active" : ""}>{path}</a>;
+}
+```
+
+### Scroll to Hash
+
+```typescript
+function ScrollToHash() {
+  const location = useLocation();
+
+  useEffect(() => {
+    if (location.hash) {
+      const element = document.querySelector(location.hash);
+      element?.scrollIntoView({ behavior: "smooth" });
+    }
+  }, [location.hash]);
+
+  return null;
+}
+```
+
+### Preserve Scroll Position
+
+```typescript
+function Layout() {
+  const location = useLocation();
+  const scrollPositions = useRef<Record<string, number>>({});
+
+  useEffect(() => {
+    // Save scroll position
+    scrollPositions.current[location.key] = window.scrollY;
+
+    // Restore scroll position
+    const savedPosition = scrollPositions.current[location.key];
+    if (savedPosition !== undefined) {
+      window.scrollTo(0, savedPosition);
+    }
+  }, [location]);
+
+  return <Outlet />;
+}
+```
+
+## useSearchParams Alternative
+
+For easier query parameter handling, use `useSearchParams`:
+
+```typescript
+import { useSearchParams } from "@tailor-platform/app-shell";
+
+function ProductsList() {
+  const [searchParams, setSearchParams] = useSearchParams();
+
+  const sort = searchParams.get("sort");
+  const page = searchParams.get("page");
+
+  const updateSort = (newSort: string) => {
+    setSearchParams({ sort: newSort, page });
+  };
+
+  return <div>...</div>;
+}
+```
+
+## Important Notes
+
+### Always Import from AppShell
+
+```typescript
+// ✅ Correct
+import { useLocation } from "@tailor-platform/app-shell";
+
+// ❌ Wrong - won't work with AppShell's router
+import { useLocation } from "react-router";
+```
+
+### Location is Immutable
+
+The location object is immutable. Don't try to modify it:
+
+```typescript
+// ❌ Wrong
+location.pathname = "/new-path";
+
+// ✅ Correct - use navigate
+navigate("/new-path");
+```
+
+## Related
+
+- [useNavigate](./use-navigate.md) - Programmatic navigation
+- [useParams](./use-params.md) - Access route parameters
+- [useSearchParams](./use-navigate.md) - Query parameter management
+- [Routing & Navigation](../../concepts/routing-navigation.md) - Navigation guide

package/skills/app-shell-patterns/references/api/router/use-navigate.md

@@ -0,0 +1,138 @@
+---
+title: useNavigate
+description: Hook for programmatic navigation between routes
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/router/use-navigate.docs.outline.md — do not edit by hand. -->
+
+# useNavigate
+
+React Router hook for programmatic navigation. Re-exported from `react-router` for convenience.
+
+## Signature
+
+```typescript
+const useNavigate: () => (to: string | number, options?: NavigateOptions) => void;
+```
+
+## Usage
+
+### Navigate to Path
+
+```typescript
+import { useNavigate } from "@tailor-platform/app-shell";
+
+function MyComponent() {
+  const navigate = useNavigate();
+
+  const goToProducts = () => {
+    navigate("/products");
+  };
+
+  return <button onClick={goToProducts}>View Products</button>;
+}
+```
+
+### Navigate with Dynamic Parameters
+
+```typescript
+function ProductCard({ id }: { id: string }) {
+  const navigate = useNavigate();
+
+  const viewDetails = () => {
+    navigate(`/products/${id}`);
+  };
+
+  return <button onClick={viewDetails}>Details</button>;
+}
+```
+
+### Navigate Back
+
+```typescript
+function BackButton() {
+  const navigate = useNavigate();
+
+  return <button onClick={() => navigate(-1)}>Back</button>;
+}
+```
+
+### Navigate Forward
+
+```typescript
+function ForwardButton() {
+  const navigate = useNavigate();
+
+  return <button onClick={() => navigate(1)}>Forward</button>;
+}
+```
+
+### Replace Current Entry
+
+```typescript
+function LoginSuccess() {
+  const navigate = useNavigate();
+
+  useEffect(() => {
+    // Replace current history entry (user can't go back to login)
+    navigate("/dashboard", { replace: true });
+  }, []);
+
+  return <div>Redirecting...</div>;
+}
+```
+
+### Navigate with State
+
+```typescript
+function ProductsList() {
+  const navigate = useNavigate();
+
+  const selectProduct = (product: Product) => {
+    navigate(`/products/${product.id}`, {
+      state: { from: "list" },
+    });
+  };
+
+  return <ProductList onSelect={selectProduct} />;
+}
+
+// Access state in target component
+function ProductDetail() {
+  const location = useLocation();
+  const from = location.state?.from; // "list"
+}
+```
+
+## NavigateOptions
+
+```typescript
+interface NavigateOptions {
+  replace?: boolean; // Replace current entry instead of pushing
+  state?: any; // Pass state to target route
+  preventScrollReset?: boolean;
+  relative?: "route" | "path";
+}
+```
+
+## Important Notes
+
+### Import from AppShell
+
+Always import from `@tailor-platform/app-shell`, not `react-router`:
+
+```typescript
+// ✅ Correct
+import { useNavigate } from "@tailor-platform/app-shell";
+
+// ❌ Wrong - won't work with AppShell's router
+import { useNavigate } from "react-router";
+```
+
+This ensures you're using AppShell's router instance.
+
+## Related
+
+- [useParams](./use-params.md) - Access route parameters
+- [useLocation](./use-location.md) - Access current location
+- [Routing & Navigation](../../concepts/routing-navigation.md) - Navigation guide, including the `Navigate` component for declarative redirects