From d9769ea9c318d4563b386cfbf0dcd60fc0bfdfde Mon Sep 17 00:00:00 2001 From: dhruveshmishra Date: Thu, 6 Aug 2026 14:57:46 +0530 Subject: [PATCH 1/6] docs: add Sistent Permission component documentation Signed-off-by: dhruveshmishra --- .../sistent/components/permission/code.mdx | 96 +++++++++++++++++++ .../components/permission/guidance.mdx | 52 ++++++++++ .../sistent/components/permission/index.mdx | 52 ++++++++++ 3 files changed, 200 insertions(+) create mode 100644 src/collections/sistent/components/permission/code.mdx create mode 100644 src/collections/sistent/components/permission/guidance.mdx create mode 100644 src/collections/sistent/components/permission/index.mdx diff --git a/src/collections/sistent/components/permission/code.mdx b/src/collections/sistent/components/permission/code.mdx new file mode 100644 index 00000000000000..fb8dc09a6a8940 --- /dev/null +++ b/src/collections/sistent/components/permission/code.mdx @@ -0,0 +1,96 @@ +--- +title: Permission Code +component: permission +description: Integration details, code examples, and API references for the PermissionShield component. +--- + +import { PermissionShield, Button } from "@sistent/sistent"; + +The `PermissionShield` component acts as a high-level wrapper to restrict and decorate interactive components. + +> **Important Security Note:** UI gating is a presentation-layer control only. Client-side checks must not decide access. The backend server and API routes must always enforce authorization on every request. + + +

Installation

+ + +```bash +npm install @sistent/sistent +``` + + +

Basic Usage

+ + +Wrap any standard component (e.g., a `Button`) inside the `PermissionShield` to automatically overlay the lock badge when permissions are restricted. + +
+
+ + + + + +
+ ( + + + +);`} /> +
+ + +

Custom Boundary Padding

+ + +Use the `boundaryPadding` prop to configure custom offsets if the tooltip overlaps fixed elements (like headers, sidebars, or navbar sections) during scrolling. + +
+
+ + + + + +
+ ( + + + +);`} /> +
+ + +

API Reference

+ + +

PermissionShield Props

+ +| Name | Type | Default | Description | +| :--- | :--- | :--- | :--- | +| `permissionKey` | `PermissionKeySpec` | - | The unique key specification that the gated action requires. | +| `children` | `React.ReactNode` | - | The gated component (e.g., Button, IconButton) to be wrapped and overlayed. | +| `variant` | `'inline' \| 'badge'` | `'inline'` | The display format of the lock badge. `'inline'` wraps/overlays children, `'badge'` displays independently. | +| `boundaryPadding` | `object` | `{ top: 85, left: 270, right: 8, bottom: 8 }` | Optional offsets to prevent tooltips from overlapping headers/menus. | diff --git a/src/collections/sistent/components/permission/guidance.mdx b/src/collections/sistent/components/permission/guidance.mdx new file mode 100644 index 00000000000000..50c8f76127e703 --- /dev/null +++ b/src/collections/sistent/components/permission/guidance.mdx @@ -0,0 +1,52 @@ +--- +title: Permission Guidance +component: permission +description: Guidance on using the Sistent Permission component and best practices for design system gating. +--- + + +

Usage

+ + +The `PermissionShield` component should be used to protect actions or affordances that require specific roles, permission keys, or capabilities. + +> **Important Security Note:** UI gating is a presentation-layer control only. Client-side checks must not decide access. The backend server and API routes must always enforce authorization on every request. + + + + +

When to Use

+ + +

Disable versus Hide

+ +When deciding whether to restrict a feature, follow these design system guidelines: + + + + +

Best Practices

+ + + diff --git a/src/collections/sistent/components/permission/index.mdx b/src/collections/sistent/components/permission/index.mdx new file mode 100644 index 00000000000000..a1931041de7c62 --- /dev/null +++ b/src/collections/sistent/components/permission/index.mdx @@ -0,0 +1,52 @@ +--- +name: "Permission" +title: "Permission" +published: true +component: permission +description: The PermissionShield component gates and protects interactive actions, buttons, and navigation elements. It displays a visual lock icon overlay or inline badge when a user lacks the necessary permission keys or capabilities. +--- + +import { PermissionShield, Button } from "@sistent/sistent"; + +The `PermissionShield` component provides a standard design pattern for feature-level permission gating across applications. Rather than silently hiding disabled elements, it keeps them visible (preserving layout continuity) and overlays a visual lock indicator to explain to users why the action is restricted. + +> **Important Security Note:** UI gating is a presentation-layer control only. Client-side checks must not decide access. The backend server and API routes must always enforce authorization on every request. + + +

Inline Shield Overlay

+ + +The default variant wraps any standard action component (like a `Button` or `IconButton`) and places a lock icon badge at the bottom-left corner of the target element. When clicked or hovered, it shows a detailed explanation of the missing permission. + + + +
+ + + +
+ + + + +

Badge Variant

+ + +The badge variant renders the permission badge independently, which is useful for list items, settings tables, or static text where a direct wrapper overlay on a button is not suitable. + + + +
+ + Audit Logs + +
+ + From e6bd037a68fb24051bc217ee4c6fb793971b99d7 Mon Sep 17 00:00:00 2001 From: dhruveshmishra Date: Sat, 8 Aug 2026 18:56:43 +0530 Subject: [PATCH 2/6] docs: update PermissionShield examples to use correct Key schema Signed-off-by: dhruveshmishra --- .../sistent/components/permission/code.mdx | 32 ++++++++++++++++--- .../sistent/components/permission/index.mdx | 16 ++++++++-- 2 files changed, 42 insertions(+), 6 deletions(-) diff --git a/src/collections/sistent/components/permission/code.mdx b/src/collections/sistent/components/permission/code.mdx index fb8dc09a6a8940..8bead1a988cebb 100644 --- a/src/collections/sistent/components/permission/code.mdx +++ b/src/collections/sistent/components/permission/code.mdx @@ -28,7 +28,13 @@ Wrap any standard component (e.g., a `Button`) inside the `PermissionShield` to
+ + +

Permission Session Context

+ + +The `PermissionSessionContext` component renders the detailed authorization metadata (user identity, organization, assigned roles, and missing keys) that is displayed inside tooltips or cards. It supports two layout variants: + +- **Tooltip Variant (`'tooltip'`):** A compact layout designed to fit inside standard hover/click tooltips (used by default inside `PermissionShield`). +- **Card Variant (`'card'`):** A theme-aware, scaled-up layout designed to be embedded directly into custom cards, sidebars, or full-page 403/Forbidden error screens. + +### Tooltip Layout + + + +
+ +
+ + + +### Card Layout + + + +
+ +
+ + + From 343d552b2160e68d6a8b20997f72b0770effe0b4 Mon Sep 17 00:00:00 2001 From: dhruveshmishra Date: Wed, 12 Aug 2026 11:05:55 +0530 Subject: [PATCH 5/6] docs: use h1 header in ForbiddenPage code example Signed-off-by: dhruveshmishra --- src/collections/sistent/components/permission/code.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/collections/sistent/components/permission/code.mdx b/src/collections/sistent/components/permission/code.mdx index 8e6580389e0898..4a8985bd4a3f28 100644 --- a/src/collections/sistent/components/permission/code.mdx +++ b/src/collections/sistent/components/permission/code.mdx @@ -133,7 +133,7 @@ Use `PermissionSessionContext` to embed permission details directly inside custo export const ForbiddenPage = () => (
-

Access Denied

+

Access Denied

Date: Thu, 13 Aug 2026 14:11:53 +0530 Subject: [PATCH 6/6] Revise title and description in code.mdx Updated metadata for Permission Code documentation. Signed-off-by: Dhruvesh Mishra --- src/collections/sistent/components/permission/code.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/collections/sistent/components/permission/code.mdx b/src/collections/sistent/components/permission/code.mdx index 4a8985bd4a3f28..6945d22132ddba 100644 --- a/src/collections/sistent/components/permission/code.mdx +++ b/src/collections/sistent/components/permission/code.mdx @@ -1,4 +1,4 @@ ---- +--- title: Permission Code component: permission description: Integration details, code examples, and API references for the PermissionShield component.