@tailor-platform/app-shell 1.14.0 → 1.16.0

package/skills/app-shell-patterns/references/components/tooltip.md

@@ -0,0 +1,144 @@
+---
+title: Tooltip
+description: Hover/focus tooltip with configurable placement and shared delay via Tooltip.Provider
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/tooltip.docs.outline.md — do not edit by hand. -->
+
+# Tooltip
+
+The `Tooltip` component displays contextual information on hover or focus. It is backed by Base UI's Tooltip primitive.
+
+## Import
+
+```tsx
+import { Tooltip } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+<example-preview name="basic-usage"></example-preview>
+
+```tsx
+function BasicUsage() {
+  return (
+    <Tooltip.Root>
+      <Tooltip.Trigger render={<Button variant="outline" />}>Hover me</Tooltip.Trigger>
+      <Tooltip.Content>Helpful information</Tooltip.Content>
+    </Tooltip.Root>
+  );
+}
+```
+
+## Sub-components
+
+| Sub-component      | Description                                                 |
+| ------------------ | ----------------------------------------------------------- |
+| `Tooltip.Provider` | Provides shared delay configuration for all nested tooltips |
+| `Tooltip.Root`     | Manages tooltip open/close state                            |
+| `Tooltip.Trigger`  | Element that shows the tooltip on hover or focus            |
+| `Tooltip.Content`  | The tooltip popup containing the help text                  |
+
+## Props
+
+### Tooltip.Provider Props
+
+Wrap a section of your UI (e.g. a toolbar) with `Tooltip.Provider` to share delay settings across multiple tooltips.
+
+| Prop         | Type              | Default | Description                                         |
+| ------------ | ----------------- | ------- | --------------------------------------------------- |
+| `delay`      | `number`          | `0`     | Delay in ms before the tooltip opens (milliseconds) |
+| `closeDelay` | `number`          | -       | Delay in ms before the tooltip closes               |
+| `timeout`    | `number`          | -       | Timeout in ms after which the tooltip auto-closes   |
+| `children`   | `React.ReactNode` | -       | Nested tooltip components                           |
+
+### Tooltip.Root Props
+
+| Prop           | Type                      | Default | Description                       |
+| -------------- | ------------------------- | ------- | --------------------------------- |
+| `open`         | `boolean`                 | -       | Controlled open state             |
+| `defaultOpen`  | `boolean`                 | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | -       | Callback when open state changes  |
+| `children`     | `React.ReactNode`         | -       | Tooltip sub-components            |
+
+### Tooltip.Content Props
+
+| Prop         | Type                                     | Default    | Description                                              |
+| ------------ | ---------------------------------------- | ---------- | -------------------------------------------------------- |
+| `side`       | `"top" \| "right" \| "bottom" \| "left"` | `"top"`    | Preferred placement of the tooltip                       |
+| `align`      | `"start" \| "center" \| "end"`           | `"center"` | Alignment along the placement axis                       |
+| `sideOffset` | `number`                                 | `5`        | Distance in px from the trigger                          |
+| `noArrow`    | `boolean`                                | `false`    | When `true`, suppresses the arrow indicator on the popup |
+| `className`  | `string`                                 | -          | Additional CSS classes                                   |
+| `children`   | `React.ReactNode`                        | -          | Tooltip text or content                                  |
+
+## Placement
+
+```tsx
+<Tooltip.Root>
+  <Tooltip.Trigger render={<Button />}>Trigger</Tooltip.Trigger>
+  <Tooltip.Content side="right" align="start">
+    Appears on the right
+  </Tooltip.Content>
+</Tooltip.Root>
+```
+
+## Shared Delay with Provider
+
+Use `Tooltip.Provider` to avoid tooltips opening immediately in dense UIs like toolbars:
+
+```tsx
+<Tooltip.Provider delay={300}>
+  <Toolbar>
+    <Tooltip.Root>
+      <Tooltip.Trigger render={<Button size="icon" />}>
+        <BoldIcon />
+      </Tooltip.Trigger>
+      <Tooltip.Content>Bold</Tooltip.Content>
+    </Tooltip.Root>
+    <Tooltip.Root>
+      <Tooltip.Trigger render={<Button size="icon" />}>
+        <ItalicIcon />
+      </Tooltip.Trigger>
+      <Tooltip.Content>Italic</Tooltip.Content>
+    </Tooltip.Root>
+  </Toolbar>
+</Tooltip.Provider>
+```
+
+## Examples
+
+### Icon Button with Tooltip
+
+```tsx
+import { PencilIcon } from "lucide-react";
+
+<Tooltip.Root>
+  <Tooltip.Trigger render={<Button size="icon" variant="ghost" />}>
+    <PencilIcon />
+    <span className="sr-only">Edit</span>
+  </Tooltip.Trigger>
+  <Tooltip.Content>Edit order</Tooltip.Content>
+</Tooltip.Root>;
+```
+
+### Controlled Tooltip
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Tooltip.Root open={open} onOpenChange={setOpen}>
+  <Tooltip.Trigger render={<Button />}>Info</Tooltip.Trigger>
+  <Tooltip.Content>Additional details here</Tooltip.Content>
+</Tooltip.Root>;
+```
+
+## Accessibility
+
+- Tooltip content is rendered in a portal
+- Trigger receives focus and keyboard activation support
+- `sr-only` text on icon-only triggers is recommended for screen readers
+
+## Related Components
+
+- [Button](./button.md) - Common trigger element for tooltips

package/skills/app-shell-patterns/references/components/with-guard.md

@@ -0,0 +1,445 @@
+---
+title: WithGuard
+description: Conditionally render UI elements based on guard evaluation with support for async permissions checks
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/with-guard.docs.outline.md — do not edit by hand. -->
+
+# WithGuard
+
+`WithGuard` is a component for conditionally rendering UI elements based on guard evaluation. It uses the same guard system as route-level guards, making permission logic reusable throughout your application.
+
+## Import
+
+```tsx
+import { WithGuard, pass, hidden } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+```tsx
+import { WithGuard, pass, hidden } from "@tailor-platform/app-shell";
+
+const isAdmin = ({ context }) => (context.currentUser?.role === "admin" ? pass() : hidden());
+
+function AdminPanel() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+
+      <WithGuard guards={[isAdmin]}>
+        <Button>Delete All Users</Button>
+      </WithGuard>
+    </div>
+  );
+}
+```
+
+If the user is not an admin, the button won't render.
+
+## Props
+
+_Generated from the type surface — first-party props only._
+
+### WithGuardProps
+
+| Prop        | Type        | Default                  | Description                                                                                                                     |
+| ----------- | ----------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| `children`  | `ReactNode` | -                        | Content to render when all guards pass.                                                                                         |
+| `fallback?` | `ReactNode` | `null (renders nothing)` | Content to render when any guard returns hidden.                                                                                |
+| `guards`    | `Guard[]`   | -                        | Guards to evaluate. All guards must pass for children to render. Uses the same Guard type as route guards for full reusability. |
+| `loading?`  | `ReactNode` | `null (renders nothing)` | Content to render while guards are being evaluated (for async guards).                                                          |
+
+## Exports
+
+- `WithGuard` — const
+- `WithGuardProps` — type
+
+## Guard Functions
+
+WithGuard uses the same `Guard` type as route guards:
+
+```typescript
+type Guard = (ctx: GuardContext) => GuardResult | Promise<GuardResult>;
+
+type GuardResult =
+  | { type: "pass" } // Allow rendering
+  | { type: "hidden" }; // Hide content (render fallback)
+```
+
+**Note:** Unlike route guards, `redirectTo()` is **not supported** in WithGuard. Use `hidden()` with a fallback that handles navigation if needed.
+
+### Creating Guards
+
+```tsx
+import { type Guard, pass, hidden } from "@tailor-platform/app-shell";
+
+// Simple guard
+const requireAuth: Guard = ({ context }) => {
+  return context.currentUser ? pass() : hidden();
+};
+
+// Async guard with API call
+const hasPermission: Guard = async ({ context }) => {
+  const canAccess = await fetch("/api/permissions/admin")
+    .then((r) => r.json())
+    .then((data) => data.allowed);
+
+  return canAccess ? pass() : hidden();
+};
+
+// Parameterized guard (curried function)
+const isOwner =
+  (resourceId: string): Guard =>
+  ({ context }) => {
+    return context.currentUser?.id === resourceId ? pass() : hidden();
+  };
+```
+
+## Examples
+
+### Simple Role Check
+
+```tsx
+const isAdmin = ({ context }) => (context.currentUser?.role === "admin" ? pass() : hidden());
+
+<WithGuard guards={[isAdmin]}>
+  <Button>Admin Settings</Button>
+</WithGuard>;
+```
+
+### With Fallback
+
+Show alternative content when guard fails:
+
+```tsx
+<WithGuard guards={[isAdmin]} fallback={<p>You need admin access to view this.</p>}>
+  <AdminPanel />
+</WithGuard>
+```
+
+### With Loading State
+
+Show loading spinner while checking permissions:
+
+```tsx
+const checkPermission: Guard = async ({ context }) => {
+  const allowed = await api.checkPermission("admin");
+  return allowed ? pass() : hidden();
+};
+
+<WithGuard guards={[checkPermission]} loading={<Spinner />} fallback={<UpgradePrompt />}>
+  <PremiumFeature />
+</WithGuard>;
+```
+
+### Multiple Guards
+
+All guards must pass for content to render:
+
+```tsx
+const isAdmin = ({ context }) => (context.currentUser?.role === "admin" ? pass() : hidden());
+
+const hasFeatureFlag = ({ context }) => (context.featureFlags?.betaFeatures ? pass() : hidden());
+
+<WithGuard guards={[isAdmin, hasFeatureFlag]}>
+  <BetaAdminFeature />
+</WithGuard>;
+```
+
+### Parameterized Guards
+
+Use curried functions to create reusable parameterized guards:
+
+```tsx
+const isOwner =
+  (resourceId: string): Guard =>
+  ({ context }) => {
+    return context.currentUser?.id === resourceId ? pass() : hidden();
+  };
+
+function ResourceActions({ resourceId }) {
+  return (
+    <WithGuard guards={[isOwner(resourceId)]}>
+      <Button>Edit</Button>
+      <Button>Delete</Button>
+    </WithGuard>
+  );
+}
+```
+
+### In Sidebar Navigation
+
+Conditionally show navigation items:
+
+```tsx
+import { DefaultSidebar, SidebarItem, WithGuard } from "@tailor-platform/app-shell";
+
+const isAdmin = ({ context }) => (context.currentUser?.role === "admin" ? pass() : hidden());
+
+<DefaultSidebar>
+  <SidebarItem to="/dashboard" />
+  <SidebarItem to="/products" />
+
+  <WithGuard guards={[isAdmin]}>
+    <SidebarItem to="/admin" />
+    <SidebarItem to="/settings" />
+  </WithGuard>
+</DefaultSidebar>;
+```
+
+### Feature Flags
+
+Toggle features based on flags:
+
+```tsx
+const hasBetaFeature = ({ context }) => (context.featureFlags?.newDashboard ? pass() : hidden());
+
+<WithGuard guards={[hasBetaFeature]} fallback={<OldDashboard />}>
+  <NewDashboard />
+</WithGuard>;
+```
+
+### Subscription Tiers
+
+Show features based on user's subscription:
+
+```tsx
+const isPremium = ({ context }) =>
+  context.currentUser?.subscription === "premium" ? pass() : hidden();
+
+<WithGuard
+  guards={[isPremium]}
+  fallback={
+    <Card>
+      <h3>Premium Feature</h3>
+      <p>Upgrade to access advanced analytics.</p>
+      <Button>Upgrade Now</Button>
+    </Card>
+  }
+>
+  <AdvancedAnalytics />
+</WithGuard>;
+```
+
+### Dynamic Permissions
+
+Check permissions from API:
+
+```tsx
+const canDeleteOrder =
+  (orderId: string): Guard =>
+  async ({ context }) => {
+    const response = await fetch(`/api/orders/${orderId}/permissions`);
+    const { canDelete } = await response.json();
+    return canDelete ? pass() : hidden();
+  };
+
+function OrderActions({ orderId }) {
+  return (
+    <div>
+      <Button>View</Button>
+      <Button>Edit</Button>
+      <WithGuard guards={[canDeleteOrder(orderId)]} loading={<Spinner size="sm" />}>
+        <Button variant="destructive">Delete</Button>
+      </WithGuard>
+    </div>
+  );
+}
+```
+
+### Combining with Route Guards
+
+Reuse the same guards for routes and UI:
+
+```tsx
+// guards.ts
+export const requireAuth: Guard = ({ context }) => {
+  return context.currentUser ? pass() : hidden();
+};
+
+export const isAdmin: Guard = ({ context }) => {
+  return context.currentUser?.role === "admin" ? pass() : hidden();
+};
+
+// routes.tsx
+const adminModule = defineModule({
+  path: "admin",
+  component: AdminPage,
+  guards: [requireAuth, isAdmin], // Route-level
+});
+
+// component.tsx
+<WithGuard guards={[requireAuth, isAdmin]}>
+  {" "}
+  {/* UI-level */}
+  <AdminSettings />
+</WithGuard>;
+```
+
+## Guard Evaluation
+
+Guards are evaluated in order and stop at the first non-pass result:
+
+```tsx
+const guards = [guardA, guardB, guardC];
+
+// If guardA returns hidden(), guardB and guardC are NOT evaluated
+<WithGuard guards={guards}>
+  <Content />
+</WithGuard>;
+```
+
+## Performance
+
+### Caching
+
+WithGuard caches guard results based on `contextData` reference:
+
+- Guards re-evaluate when `contextData` changes
+- Guards do NOT re-evaluate when props change (except `guards` array)
+
+### Suspense Integration
+
+Async guards use React Suspense:
+
+- Shows `loading` prop while evaluating
+- Renders `children` or `fallback` when complete
+- Automatically suspends during evaluation
+
+## Context Data
+
+Guards receive the same context as route guards:
+
+```typescript
+// Define context type
+declare module "@tailor-platform/app-shell" {
+  interface AppShellRegister {
+    contextData: {
+      currentUser: User | null;
+      featureFlags: FeatureFlags;
+      permissions: string[];
+    };
+  }
+}
+
+// Use in guards
+const hasPermission =
+  (perm: string): Guard =>
+  ({ context }) => {
+    return context.permissions.includes(perm) ? pass() : hidden();
+  };
+```
+
+## Comparison: WithGuard vs Route Guards
+
+| Feature                     | WithGuard                | Route Guards                |
+| --------------------------- | ------------------------ | --------------------------- |
+| **Purpose**                 | Conditional UI rendering | Route access control        |
+| **Location**                | Inside components        | Module/resource definitions |
+| **Supports `pass()`**       | ✅ Yes                   | ✅ Yes                      |
+| **Supports `hidden()`**     | ✅ Yes                   | ✅ Yes                      |
+| **Supports `redirectTo()`** | ❌ No                    | ✅ Yes                      |
+| **Async guards**            | ✅ Yes                   | ✅ Yes                      |
+| **Reusable**                | ✅ Yes                   | ✅ Yes                      |
+
+## Best Practices
+
+### Do:
+
+- ✅ Reuse guards between routes and UI
+- ✅ Use descriptive guard names (`isAdmin`, `canEdit`)
+- ✅ Provide fallback for better UX
+- ✅ Show loading state for async guards
+- ✅ Cache expensive permission checks
+
+### Don't:
+
+- ❌ Use `redirectTo()` in WithGuard (not supported)
+- ❌ Make guards too complex (extract to functions)
+- ❌ Forget to handle loading states
+- ❌ Skip fallback when hiding important features
+- ❌ Duplicate permission logic (reuse guards)
+
+## Accessibility
+
+- Content is fully removed from DOM when hidden (not just visually)
+- Screen readers won't announce hidden content
+- Loading states should be announced to screen readers
+- Fallback content should be accessible
+
+## TypeScript
+
+Full type safety with TypeScript:
+
+```typescript
+import { type Guard, type WithGuardProps } from "@tailor-platform/app-shell";
+
+// Type-safe guard
+const isAdmin: Guard = ({ context }) => {
+  // context is fully typed
+  return context.currentUser?.role === "admin" ? pass() : hidden();
+};
+
+// Type-safe props
+const guardProps: WithGuardProps = {
+  guards: [isAdmin],
+  children: <AdminPanel />,
+  fallback: <AccessDenied />,
+};
+```
+
+## Troubleshooting
+
+### Guard not re-evaluating
+
+**Problem:** Guard doesn't update when data changes
+
+**Solution:** Ensure `contextData` reference changes:
+
+```tsx
+// ❌ Bad - mutating object
+context.currentUser.role = "admin";
+
+// ✅ Good - new reference
+setContextData({
+  ...contextData,
+  currentUser: { ...currentUser, role: "admin" },
+});
+```
+
+### Infinite loading
+
+**Problem:** Loading state never resolves
+
+**Solution:** Ensure async guards return a result:
+
+```tsx
+// ❌ Bad - no return
+const checkPermission: Guard = async ({ context }) => {
+  await fetch("/api/check");
+  // Missing return!
+};
+
+// ✅ Good - returns result
+const checkPermission: Guard = async ({ context }) => {
+  const allowed = await fetch("/api/check").then((r) => r.json());
+  return allowed ? pass() : hidden();
+};
+```
+
+## Related Components
+
+- [AppShell](./app-shell.md) - Context provider for guards
+- [SidebarItem](./sidebar-item.md) - Use WithGuard in navigation
+
+## Related Concepts
+
+- [Guards and Permissions](../api/guards/overview.md) - Comprehensive guard guide
+- [Modules and Resources](../concepts/modules-and-resources.md) - Route-level guards
+
+## API Reference
+
+- [pass()](../api/guards/pass.md) - Allow access guard
+- [hidden()](../api/guards/hidden.md) - Hide content guard
+- [Guards Overview](../api/guards/overview.md) - Complete guard reference