@kortix/ui 0.0.0-stage → 0.14.4

package/dist/access/access/access-row.d.ts

@@ -0,0 +1,106 @@
+import type { ReactNode } from 'react';
+/** The entity-row dialect the customize section views established. */
+export declare const ACCESS_ROW_CLASS = "bg-popover flex items-center gap-3 rounded-md border px-4 py-2.5";
+/**
+ * One kebab action. Flat list only — no submenus, no radio groups. A role
+ * change is not a menu item; it opens `AccessDialog`.
+ */
+export interface KebabItem {
+    label: string;
+    icon?: ReactNode;
+    /** Runs on activation. Optional when the item only navigates — pass `href`. */
+    onSelect?: () => void;
+    /**
+     * Destination known at render. The item becomes a real `<Link>`, so Next
+     * prefetches the payload and the click stays a client navigation instead of
+     * running a cold RSC fetch that can degrade into a full page load.
+     */
+    href?: string;
+    variant?: 'default' | 'destructive';
+    disabled?: boolean;
+    /** Tooltip on the item, e.g. why it is disabled. */
+    hint?: string;
+    /** Draws a separator above this item. */
+    separated?: boolean;
+}
+export interface AccessRowSelectable {
+    checked: boolean;
+    onCheckedChange: () => void;
+    /** Accessible name, e.g. `Select alice@corp.com`. */
+    label: string;
+    disabled?: boolean;
+    /**
+     * This row is not selectable but a sibling is — reserve the checkbox
+     * width so every avatar still lines up on one column.
+     */
+    reserveSpace?: boolean;
+}
+export interface AccessRowProps {
+    /** `UserAvatar` / `EntityAvatar` / tinted icon tile. */
+    leading?: ReactNode;
+    title: ReactNode;
+    /** Rendered next to the title. Pass `Badge` elements. */
+    badges?: ReactNode;
+    /** Meta line under the title — wrap plain strings in `InlineMeta` yourself,
+     *  or pass `metaParts` and let the row do it. */
+    meta?: ReactNode;
+    /** Convenience: `string[]` rendered through `InlineMeta`. */
+    metaParts?: ReactNode[];
+    /** Right-hand label — a role name, a status. */
+    trailing?: ReactNode;
+    /** Inline ghost buttons before the kebab (Approve / Decline, Resend / Revoke). */
+    actions?: ReactNode;
+    kebab?: KebabItem[];
+    /** Accessible name for the kebab trigger. Defaults to "Actions". */
+    kebabLabel?: string;
+    /** Row click target. The row becomes keyboard-activatable. */
+    onClick?: () => void;
+    /**
+     * Row destination, when it is known at render. The row gets a stretched
+     * `<Link>` overlay instead of a click handler, so the payload prefetches and
+     * the click never runs a cold RSC fetch. Same pattern as a clickable `Card`
+     * (`packages/ui/src/primitives/card.tsx`).
+     */
+    href?: string;
+    selectable?: AccessRowSelectable;
+    /** Swaps the kebab for a spinner while a mutation on this row is in flight. */
+    pending?: boolean;
+    /** Pending-invite styling. */
+    dashed?: boolean;
+    /**
+     * This grant cannot be edited here (implicit owner/admin access, or
+     * inherited from a group). Renders a `Shield` + `Hint` where the kebab
+     * would be — ported from `access-projects-tab.tsx:1280-1293`.
+     */
+    notEditable?: {
+        hint: string;
+    };
+    className?: string;
+}
+export declare function AccessRow({ leading, title, badges, meta, metaParts, trailing, actions, kebab, kebabLabel, onClick, href, selectable, pending, dashed, notEditable, className, }: AccessRowProps): import("react").JSX.Element;
+/** The row's kebab, exported for table-shaped lists (API tokens, OAuth apps) that keep its menu. */
+export declare function RowKebab({ items, label }: {
+    items: KebabItem[];
+    label: string;
+}): import("react").JSX.Element;
+export interface AccessListSelection {
+    selectedIds: ReadonlySet<string> | readonly string[];
+    /** Rows that can be bulk-acted on — self rows are usually excluded. */
+    eligibleIds: readonly string[];
+    onToggleAll: () => void;
+}
+export interface AccessListHeader {
+    title: ReactNode;
+    count?: number;
+    /** Right-aligned header actions — a "+ Grant access" button, filters. */
+    actions?: ReactNode;
+}
+export interface AccessListProps {
+    children: ReactNode;
+    header?: AccessListHeader;
+    /** Renders the "Select all visible" control in the header. Row checkboxes
+     *  come from each `AccessRow`'s own `selectable`. */
+    selectable?: AccessListSelection;
+    className?: string;
+}
+export declare function AccessList({ children, header, selectable, className }: AccessListProps): import("react").JSX.Element;

package/dist/access/access/access-row.js

@@ -0,0 +1,79 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useTranslations } from '../../i18n/index.js';
+// AccessList / AccessRow — THE list row for every access surface.
+//
+// Canonical anatomy, extracted faithfully from the account `MembersCard`
+// list (`features/accounts/hub/account-hub-content.tsx:1443-1676`): a `bg-popover
+// rounded-md border` stack, an optional bulk checkbox, a `UserAvatar` /
+// `EntityAvatar`, title + badges, an `InlineMeta` meta line, a trailing
+// role label, and a kebab `DropdownMenu`.
+//
+// It replaces the three `MEMBER_ROW` copies, the project Access `Table`,
+// the `PolicyAssignments` table, the roles table, and the six ad hoc
+// `<ul>` lists across groups / agents / audit-webhooks.
+import { Button } from '../../primitives/button.js';
+import { Checkbox } from '../../primitives/checkbox.js';
+import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger, } from '../../primitives/dropdown-menu.js';
+import Hint from '../../primitives/hint.js';
+import { InlineMeta } from '../../primitives/inline-meta.js';
+import Loading from '../../primitives/loading.js';
+import { cn } from '../../internal/lib/utils.js';
+import { DotsThreeIcon, ShieldIcon } from '@phosphor-icons/react';
+import { UiLink as Link } from '../../providers/ui-provider.js';
+/** The entity-row dialect the customize section views established. */
+export const ACCESS_ROW_CLASS = 'bg-popover flex items-center gap-3 rounded-md border px-4 py-2.5';
+export function AccessRow({ leading, title, badges, meta, metaParts, trailing, actions, kebab, kebabLabel = 'Actions', onClick, href, selectable, pending = false, dashed = false, notEditable, className, }) {
+    const linked = !!href;
+    const interactive = linked || !!onClick;
+    const items = kebab?.filter(Boolean) ?? [];
+    const hasTrailingSlot = !!trailing || !!actions || items.length > 0 || pending || !!notEditable;
+    return (_jsxs("li", { className: cn(ACCESS_ROW_CLASS, 'transition-colors', linked && 'relative', dashed && 'border-dashed', interactive && 'hover:bg-primary/[0.04] cursor-pointer', className), ...(interactive && !linked
+            ? {
+                role: 'button',
+                tabIndex: 0,
+                onClick,
+                onKeyDown: (event) => {
+                    if (event.key !== 'Enter' && event.key !== ' ')
+                        return;
+                    event.preventDefault();
+                    onClick?.();
+                },
+            }
+            : {}), children: [href ? (
+            // Stretched overlay: the anchor covers the whole row, so the row is one
+            // click target and one tab stop, while the checkbox and the trailing
+            // actions sit above it and stay independently clickable.
+            _jsx(Link, { href: href, onClick: onClick, "aria-label": typeof title === 'string' ? title : undefined, className: "absolute inset-0 z-10 rounded-[inherit] outline-none focus-visible:ring-1 focus-visible:ring-[color:var(--focus-ring,#6B97FF)]" })) : null, selectable ? (selectable.reserveSpace ? (
+            // This row is not selectable (it's you) but a sibling is — reserve
+            // the same width so every avatar lines up on one column.
+            _jsx("span", { "aria-hidden": true, className: "size-[18px] shrink-0" })) : (_jsx(Checkbox, { checked: selectable.checked, disabled: selectable.disabled, onCheckedChange: selectable.onCheckedChange, onClick: (event) => event.stopPropagation(), "aria-label": selectable.label, className: cn(linked && 'relative z-20') }))) : null, leading, _jsxs("div", { className: "min-w-0 flex-1", children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsx("span", { className: "text-foreground truncate text-sm font-medium", children: title }), badges] }), meta ??
+                        (metaParts && metaParts.length > 0 ? (_jsx("div", { className: "text-muted-foreground text-xs", children: _jsx(InlineMeta, { children: metaParts.map((part, i) => (_jsx("span", { children: part }, i))) }) })) : null)] }), hasTrailingSlot ? (_jsxs("div", { className: cn('flex shrink-0 items-center gap-1.5', linked && 'relative z-20'), onClick: (event) => event.stopPropagation(), onKeyDown: (event) => event.stopPropagation(), role: "presentation", children: [trailing ? _jsx("span", { className: "text-muted-foreground text-sm", children: trailing }) : null, actions, pending || notEditable || items.length > 0 ? (_jsx("div", { className: "flex w-7 shrink-0 justify-end", children: pending ? (_jsx(Loading, { className: "text-muted-foreground size-4 shrink-0" })) : notEditable ? (_jsx(Hint, { side: "top", label: notEditable.hint, children: _jsx("span", { className: "text-muted-foreground inline-flex size-7 items-center justify-center", children: _jsx(ShieldIcon, { className: "size-3.5" }) }) })) : items.length > 0 ? (_jsx(RowKebab, { items: items, label: kebabLabel })) : null })) : null] })) : null] }));
+}
+/** The row's kebab, exported for table-shaped lists (API tokens, OAuth apps) that keep its menu. */
+export function RowKebab({ items, label }) {
+    return (_jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsx(Button, { variant: "ghost", size: "icon", className: "text-muted-foreground hover:text-foreground size-7", "aria-label": label, children: _jsx(DotsThreeIcon, { className: "size-3.5" }) }) }), _jsx(DropdownMenuContent, { align: "end", className: "w-56", children: items.map((item, index) => {
+                    const content = (_jsxs(_Fragment, { children: [item.icon, item.label] }));
+                    const node = (_jsx(DropdownMenuItem, { 
+                        // A destination known at render is an anchor, never a handler —
+                        // `onSelect` keeps the side effects and the anchor navigates.
+                        asChild: !!item.href, variant: item.variant, disabled: item.disabled, onSelect: item.onSelect, className: "gap-2", children: item.href ? _jsx(Link, { href: item.href, children: content }) : content }, item.label));
+                    // A disabled item carries its reason as `hint` — a plain disabled
+                    // row says nothing about why.
+                    const wrapped = item.hint && item.disabled ? (_jsx(Hint, { side: "left", label: item.hint, children: _jsx("div", { children: node }) })) : (node);
+                    return (_jsxs("div", { children: [item.separated && index > 0 ? _jsx(DropdownMenuSeparator, {}) : null, wrapped] }, item.label));
+                }) })] }));
+}
+export function AccessList({ children, header, selectable, className }) {
+    const tI18nComplete = useTranslations('hardcodedUi.i18nComplete');
+    const selected = selectable
+        ? selectable.selectedIds instanceof Set
+            ? selectable.selectedIds
+            : new Set(selectable.selectedIds)
+        : null;
+    const eligible = selectable?.eligibleIds ?? [];
+    const allSelected = !!selected && eligible.length > 0 && eligible.every((id) => selected.has(id));
+    return (_jsxs("div", { className: cn('space-y-2', className), children: [header || (selectable && eligible.length > 0) ? (_jsxs("div", { className: "flex items-center justify-between gap-3 px-1", children: [_jsxs("span", { className: "text-muted-foreground text-xs font-medium", children: [header?.title, typeof header?.count === 'number' ? ` · ${header.count}` : ''] }), _jsxs("div", { className: "flex items-center gap-3", children: [selectable && eligible.length > 0 ? (_jsxs("label", { className: "text-muted-foreground flex cursor-pointer items-center gap-2 text-xs", children: [_jsx(Checkbox, { checked: allSelected, onCheckedChange: selectable.onToggleAll }), allSelected
+                                        ? tI18nComplete.raw('text967549497036')
+                                        : tI18nComplete.raw('textb48c0322c628')] })) : null, header?.actions] })] })) : null, _jsx("ul", { className: "space-y-2", children: children })] }));
+}

package/dist/access/access/access-shared.d.ts

@@ -0,0 +1,86 @@
+import type { UiTranslator } from '../../i18n/index.js';
+/**
+ * The exact wording the backend's `requireEntitlement('rbac')` 402 uses —
+ * keep it in sync with apps/api/src/accounts/iam/http-helpers.ts
+ * `ENTITLEMENT_LABEL.rbac`.
+ *
+ * Replaces the four verbatim copies that lived in `roles-tab.tsx`,
+ * `groups-tab.tsx`, `policy-assignments.tsx` and
+ * `accounts/[id]/groups/[groupId]/page.tsx`.
+ */
+export declare const RBAC_UPSELL_MESSAGE = "Custom roles, policies, and groups need Enterprise. An owner or admin can turn on the Enterprise demo, or talk to sales for a license.";
+/**
+ * How a principal is labelled in every list, row, dialog and confirm.
+ * Email when we have one, otherwise the raw id — the same `email ||
+ * user_id` fallback that was written out inline in `page.tsx`
+ * (`memberLabel`), `access-agents-tab.tsx` (`accountMemberLabel`) and
+ * `access-projects-tab.tsx` (`userLabel`).
+ */
+export declare function principalLabel(principal: {
+    email?: string | null;
+    user_id?: string | null;
+    name?: string | null;
+} | null | undefined): string;
+/** Shortened principal id, for surfaces that only have a raw uuid. */
+export declare function shortPrincipalId(userId: string): string;
+/**
+ * "just now" / "12m ago" / "3h ago" / "9d ago" / absolute date past 30
+ * days. Byte-for-byte the ladder that `audit-tab.tsx` and `scim-card.tsx`
+ * each carried their own copy of; this version takes both an ISO string
+ * and a `Date` so both call sites collapse onto it.
+ */
+export declare function formatRelative(input: string | Date | null | undefined): string;
+/** "Aug 18, 2026" — the row-meta date used by every access list. */
+export declare function formatDate(input: string | null | undefined): string;
+export interface ExpiryDisplay {
+    /** "Never" when there is no expiry, otherwise the formatted date. */
+    label: string;
+    /** true once the timestamp is in the past. */
+    expired: boolean;
+    /** false when there is no expiry at all — render it muted. */
+    bounded: boolean;
+}
+/**
+ * The `ExpiresCell` logic from `access-projects-tab.tsx:1186-1195`, minus
+ * the JSX: no expiry = permanent "Never"; a past timestamp is flagged so
+ * the row can paint it `text-kortix-red` instead of `text-kortix-yellow`.
+ */
+export declare function formatExpiry(expiresAt: string | null | undefined, tI18nComplete: UiTranslator): ExpiryDisplay;
+/**
+ * `<input type="date">` value → ISO instant at the END of that day, in the
+ * admin's own timezone. A bare `YYYY-MM-DD` parses as UTC midnight, which
+ * reads as the day BEFORE for western-timezone admins — ported from
+ * `policy-assignments.tsx`'s `CreateAssignmentDialog`.
+ *
+ * Returns `undefined` for an empty value so callers can spread it into a
+ * payload without sending `expires_at: null` by accident.
+ */
+export declare function endOfLocalDayIso(dateValue: string): string | undefined;
+/** ISO instant → the `YYYY-MM-DD` an `<input type="date">` wants back. */
+export declare function isoToDateInputValue(iso: string | null | undefined): string;
+export interface RemoveAccessCopyInput {
+    /** Display label of the principal losing access. */
+    principal: string;
+    /** Where they lose it — an account name, a project name, a group name. */
+    scopeName: string;
+    /**
+     * Groups that keep granting them access after the direct grant is gone.
+     * Pass the group names; an empty list / omission means the removal is
+     * total.
+     */
+    inherited?: string[];
+}
+export interface ConfirmCopy {
+    title: string;
+    description: string;
+}
+/**
+ * The ONE destructive-confirm copy builder for "this principal should no
+ * longer have access here". Every remove/revoke/detach confirm in the
+ * access surface uses it, always with `confirmVariant="destructive"`.
+ */
+export declare function removeAccessCopy({ principal, scopeName, inherited }: RemoveAccessCopyInput, tI18nComplete: UiTranslator): ConfirmCopy;
+/** "a", "a and b", "a, b and c" — used by `removeAccessCopy`'s inherited note. */
+export declare function formatList(items: readonly string[]): string;
+/** "1 project" / "3 projects" — the meta-line pluraliser every row needs. */
+export declare function pluralize(count: number, singular: string, plural?: string): string;

package/dist/access/access/access-shared.js

@@ -0,0 +1,143 @@
+// Shared, framework-free helpers for every access-control surface.
+//
+// One copy of each string / formatter that used to live in three or four
+// IAM files at once. Nothing here imports React — it is all pure so the
+// unit tests can call it directly (`access-shared.test.ts`).
+/**
+ * The exact wording the backend's `requireEntitlement('rbac')` 402 uses —
+ * keep it in sync with apps/api/src/accounts/iam/http-helpers.ts
+ * `ENTITLEMENT_LABEL.rbac`.
+ *
+ * Replaces the four verbatim copies that lived in `roles-tab.tsx`,
+ * `groups-tab.tsx`, `policy-assignments.tsx` and
+ * `accounts/[id]/groups/[groupId]/page.tsx`.
+ */
+export const RBAC_UPSELL_MESSAGE = 'Custom roles, policies, and groups need Enterprise. An owner or admin can turn on the Enterprise demo, or talk to sales for a license.';
+/**
+ * How a principal is labelled in every list, row, dialog and confirm.
+ * Email when we have one, otherwise the raw id — the same `email ||
+ * user_id` fallback that was written out inline in `page.tsx`
+ * (`memberLabel`), `access-agents-tab.tsx` (`accountMemberLabel`) and
+ * `access-projects-tab.tsx` (`userLabel`).
+ */
+export function principalLabel(principal) {
+    if (!principal)
+        return '';
+    return principal.email || principal.name || principal.user_id || '';
+}
+/** Shortened principal id, for surfaces that only have a raw uuid. */
+export function shortPrincipalId(userId) {
+    return userId.slice(0, 8);
+}
+// Module-scope formatters: constructing `Intl.DateTimeFormat` is the
+// expensive half, and these (locale, options) pairs are static.
+const relativeFallbackFormat = new Intl.DateTimeFormat();
+const rowDateFormat = new Intl.DateTimeFormat(undefined, {
+    month: 'short',
+    day: 'numeric',
+    year: 'numeric',
+});
+/**
+ * "just now" / "12m ago" / "3h ago" / "9d ago" / absolute date past 30
+ * days. Byte-for-byte the ladder that `audit-tab.tsx` and `scim-card.tsx`
+ * each carried their own copy of; this version takes both an ISO string
+ * and a `Date` so both call sites collapse onto it.
+ */
+export function formatRelative(input) {
+    if (!input)
+        return '—';
+    const date = input instanceof Date ? input : new Date(input);
+    if (Number.isNaN(date.getTime()))
+        return '—';
+    const minutes = Math.floor((Date.now() - date.getTime()) / 60_000);
+    if (minutes < 1)
+        return 'just now';
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    if (days < 30)
+        return `${days}d ago`;
+    return relativeFallbackFormat.format(date);
+}
+/** "Aug 18, 2026" — the row-meta date used by every access list. */
+export function formatDate(input) {
+    if (!input)
+        return '—';
+    const date = new Date(input);
+    if (Number.isNaN(date.getTime()))
+        return '—';
+    return rowDateFormat.format(date);
+}
+/**
+ * The `ExpiresCell` logic from `access-projects-tab.tsx:1186-1195`, minus
+ * the JSX: no expiry = permanent "Never"; a past timestamp is flagged so
+ * the row can paint it `text-kortix-red` instead of `text-kortix-yellow`.
+ */
+export function formatExpiry(expiresAt, tI18nComplete) {
+    if (!expiresAt)
+        return { label: tI18nComplete.raw('text6300ef800bb8'), expired: false, bounded: false };
+    const date = new Date(expiresAt);
+    if (Number.isNaN(date.getTime()))
+        return { label: '—', expired: false, bounded: true };
+    return {
+        label: rowDateFormat.format(date),
+        expired: date.getTime() < Date.now(),
+        bounded: true,
+    };
+}
+/**
+ * `<input type="date">` value → ISO instant at the END of that day, in the
+ * admin's own timezone. A bare `YYYY-MM-DD` parses as UTC midnight, which
+ * reads as the day BEFORE for western-timezone admins — ported from
+ * `policy-assignments.tsx`'s `CreateAssignmentDialog`.
+ *
+ * Returns `undefined` for an empty value so callers can spread it into a
+ * payload without sending `expires_at: null` by accident.
+ */
+export function endOfLocalDayIso(dateValue) {
+    if (!dateValue)
+        return undefined;
+    const parsed = new Date(`${dateValue}T23:59:59`);
+    if (Number.isNaN(parsed.getTime()))
+        return undefined;
+    return parsed.toISOString();
+}
+/** ISO instant → the `YYYY-MM-DD` an `<input type="date">` wants back. */
+export function isoToDateInputValue(iso) {
+    if (!iso)
+        return '';
+    const date = new Date(iso);
+    if (Number.isNaN(date.getTime()))
+        return '';
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+/**
+ * The ONE destructive-confirm copy builder for "this principal should no
+ * longer have access here". Every remove/revoke/detach confirm in the
+ * access surface uses it, always with `confirmVariant="destructive"`.
+ */
+export function removeAccessCopy({ principal, scopeName, inherited }, tI18nComplete) {
+    const base = `${principal} loses access to ${scopeName}.`;
+    if (!inherited || inherited.length === 0)
+        return { title: tI18nComplete.raw('text914d43beac26'), description: base };
+    return {
+        title: tI18nComplete.raw('text914d43beac26'),
+        description: tI18nComplete('textc3bb47ef2fd9', { value0: base, value1: formatList(inherited) }),
+    };
+}
+/** "a", "a and b", "a, b and c" — used by `removeAccessCopy`'s inherited note. */
+export function formatList(items) {
+    if (items.length === 0)
+        return '';
+    if (items.length === 1)
+        return items[0];
+    return `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`;
+}
+/** "1 project" / "3 projects" — the meta-line pluraliser every row needs. */
+export function pluralize(count, singular, plural = `${singular}s`) {
+    return `${count} ${count === 1 ? singular : plural}`;
+}

package/dist/access/access/account-role-editor.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `useAccountRoleEditor` — the ONE way a surface edits a person's ACCOUNT
+ * role. The account Members list and a group's Members list both show people,
+ * and both offer the same "Edit access" row action. That action opens the
+ * shared `AccessDialog` in account-scope edit mode, seeded with the person's
+ * current role.
+ *
+ * A member's account role is ONE value: a built-in role (`owner` / `admin` /
+ * `member`), or a custom role that rides on the `member` baseline plus one
+ * account-scoped `iam_policies` row. Resolving the custom half needs two
+ * independent gates, and both must hold:
+ *
+ *  1. ENTITLEMENT (`rbacEnabled`) — without `rbac` there are no custom roles
+ *     and no policies to resolve.
+ *  2. PERMISSION (`canReadPolicies`) — `GET .../iam/policies` asserts
+ *     `policy.read`, which a plain member does not hold
+ *     (`apps/api/src/iam/role-perms.ts`). `=== true`, not `!== false`: a
+ *     permission probe reads `false` while in flight, and an optimistic gate
+ *     fires the request it exists to suppress.
+ *
+ * The query key is the Members list's own key, so every surface shares one
+ * cached read and `AccessDialog`'s invalidation refreshes all of them.
+ */
+import { type AccountRole } from '@kortix/sdk';
+import { type ReactNode } from 'react';
+import { type AccessDialogResult } from './access-dialog.js';
+import { type RoleValue } from './role-select.js';
+export interface AccountRoleEditTarget {
+    userId: string;
+    label: string;
+    accountRole: AccountRole;
+}
+export interface UseAccountRoleEditorOptions {
+    accountId: string;
+    /** Used in the dialog copy. Defaults to "this account" inside the dialog. */
+    accountName?: string;
+    rbacEnabled: boolean;
+    /** `policy.read` — see the module note. */
+    canReadPolicies: boolean;
+    /** Shows the "Create a custom role →" link inside the role select. */
+    canManageRoles: boolean;
+    onDone?: (result: AccessDialogResult) => void;
+}
+export interface AccountRoleEditor {
+    /** The person's current account role, custom role included once resolved. */
+    roleValueFor: (userId: string, accountRole: AccountRole) => RoleValue;
+    /** Opens the edit dialog for one person. */
+    openEdit: (target: AccountRoleEditTarget) => void;
+    /** Render once, anywhere in the surface's tree. */
+    dialog: ReactNode;
+}
+export declare function useAccountRoleEditor({ accountId, accountName, rbacEnabled, canReadPolicies, canManageRoles, onDone, }: UseAccountRoleEditorOptions): AccountRoleEditor;

package/dist/access/access/account-role-editor.js

@@ -0,0 +1,63 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * `useAccountRoleEditor` — the ONE way a surface edits a person's ACCOUNT
+ * role. The account Members list and a group's Members list both show people,
+ * and both offer the same "Edit access" row action. That action opens the
+ * shared `AccessDialog` in account-scope edit mode, seeded with the person's
+ * current role.
+ *
+ * A member's account role is ONE value: a built-in role (`owner` / `admin` /
+ * `member`), or a custom role that rides on the `member` baseline plus one
+ * account-scoped `iam_policies` row. Resolving the custom half needs two
+ * independent gates, and both must hold:
+ *
+ *  1. ENTITLEMENT (`rbacEnabled`) — without `rbac` there are no custom roles
+ *     and no policies to resolve.
+ *  2. PERMISSION (`canReadPolicies`) — `GET .../iam/policies` asserts
+ *     `policy.read`, which a plain member does not hold
+ *     (`apps/api/src/iam/role-perms.ts`). `=== true`, not `!== false`: a
+ *     permission probe reads `false` while in flight, and an optimistic gate
+ *     fires the request it exists to suppress.
+ *
+ * The query key is the Members list's own key, so every surface shares one
+ * cached read and `AccessDialog`'s invalidation refreshes all of them.
+ */
+import { listPolicies } from '@kortix/sdk';
+import { useQuery } from '@tanstack/react-query';
+import { useCallback, useMemo, useState } from 'react';
+import { AccessDialog } from './access-dialog.js';
+import { builtinRole, customRole } from './role-select.js';
+export function useAccountRoleEditor({ accountId, accountName, rbacEnabled, canReadPolicies, canManageRoles, onDone, }) {
+    const [target, setTarget] = useState(null);
+    const policiesQuery = useQuery({
+        queryKey: ['iam-policies', accountId],
+        queryFn: () => listPolicies(accountId),
+        enabled: rbacEnabled && canReadPolicies === true,
+        staleTime: 30_000,
+    });
+    const accountPolicyByUser = useMemo(() => {
+        const map = new Map();
+        for (const policy of policiesQuery.data ?? []) {
+            if (policy.principal_type === 'member' && policy.scope_type === 'account') {
+                map.set(policy.principal_id, policy);
+            }
+        }
+        return map;
+    }, [policiesQuery.data]);
+    const roleValueFor = useCallback((userId, accountRole) => {
+        const policy = accountPolicyByUser.get(userId);
+        return policy ? customRole(policy.role_id) : builtinRole(accountRole);
+    }, [accountPolicyByUser]);
+    const dialog = target ? (_jsx(AccessDialog, { open: true, onOpenChange: (open) => {
+            if (!open)
+                setTarget(null);
+        }, accountId: accountId, accountName: accountName, scope: { kind: 'account' }, mode: {
+            kind: 'edit',
+            principal: { type: 'member', id: target.userId, label: target.label },
+            // No `assignmentId`: the policies read carries legacy policy ids,
+            // which are NOT assignment ids. The dialog reads the row back.
+            current: { role: roleValueFor(target.userId, target.accountRole) },
+        }, rbacEnabled: rbacEnabled, canManageRoles: canManageRoles, onDone: onDone }, target.userId)) : null;
+    return { roleValueFor, openEdit: setTarget, dialog };
+}

package/dist/access/access/agent-principals.d.ts

@@ -0,0 +1,97 @@
+import { type AgentIdentity, type IamRole, type RoleAssignment } from '@kortix/sdk';
+/** Never an agent's, whatever its role or its `kortix_permissions` say. Mirrors
+ *  `HUMAN_ONLY_ACTIONS` in apps/api `iam/agent-principal.ts`: a token an agent
+ *  minted would carry none of its permissions. */
+export declare const HUMAN_ONLY_PERMISSIONS: readonly string[];
+/** Every project permission `kortix_permissions` may name. */
+export declare const GRANTABLE_PROJECT_PERMISSIONS: readonly string[];
+export type PermissionGrant = string[] | 'all' | '*' | 'none' | undefined;
+export interface AgentAuthority {
+    /** The manifest grant, expanded: `all` → every grantable permission. */
+    declared: string[];
+    /** What the agent may do on shared project resources, sorted. */
+    effective: string[];
+    /** Declared, but outside the ceiling role(s). */
+    outsideCeiling: string[];
+    /** Declared, but human-only — dropped whatever the ceiling says. */
+    humanOnly: string[];
+}
+export declare function expandPermissionGrant(grant: PermissionGrant): string[];
+/**
+ * The intersection, as the server computes it. `ceiling === null` means no
+ * role is bound to the agent's service account: the built-in default ceiling
+ * applies, which is every grantable project permission minus HUMAN_ONLY.
+ */
+export declare function computeAgentAuthority(grant: PermissionGrant, ceiling: readonly string[] | null): AgentAuthority;
+/** The service account an agent runs as in one project, or null. */
+export declare function agentIdentityFor(identities: readonly AgentIdentity[] | undefined, projectId: string, agentName: string): AgentIdentity | null;
+/**
+ * The ceiling-bearing assignments of one agent in one project: role rows (not
+ * object grants) bound to its service account at the project, or at the
+ * account (which covers every project).
+ */
+export declare function ceilingAssignments(assignments: readonly RoleAssignment[] | undefined, serviceAccountId: string, projectId: string): RoleAssignment[];
+/**
+ * The id `GET /iam/roles/:roleId/permissions` answers for an assignment's role.
+ * A custom role is addressed by its assignment `role_id`. A system role is
+ * not: the assignment carries the seeded row's uuid, while the route knows
+ * system roles by their wire id (`builtin:user` is the project `member`), so
+ * it is looked up in the roles list by key and scope. Null when the roles list
+ * does not name it.
+ */
+export declare function rolePermissionsId(assignment: Pick<RoleAssignment, 'role_id' | 'role_key' | 'role_is_system' | 'scope_type'>, roles: readonly Pick<IamRole, 'role_id' | 'key' | 'is_system' | 'resource_type'>[] | undefined): string | null;
+export declare const agentIdentitiesQueryKey: (accountId: string | undefined) => readonly ["iam-agent-identities", string | undefined];
+export declare const projectAgentIdentitiesQueryKey: (projectId: string | undefined) => readonly ["project-agent-identities", string | undefined];
+/**
+ * The account's agent identities. Admin-only: the route asserts `policy.read`,
+ * and a 403 is an answer ("you cannot see the ceiling"), not an error to toast.
+ */
+/** One project's agent identities — readable by any project member. */
+export declare function useProjectAgentIdentities(projectId: string | undefined, enabled?: boolean): import("@tanstack/react-query").UseQueryResult<AgentIdentity[], Error>;
+export declare function useAgentIdentities(accountId: string | undefined, enabled?: boolean): import("@tanstack/react-query").UseQueryResult<AgentIdentity[], Error>;
+/** Query key for one account's IAM roles list — shared by every reader
+ *  (`useAgentAuthority` below, `ProjectAgentAccessList`) and by the early
+ *  prefetch in `access-projects-tab.tsx`, so all three land in one cache
+ *  entry instead of the literal `['iam-roles', accountId]` drifting between
+ *  hand-copied call sites. */
+export declare const agentRolesQueryKey: (accountId: string | undefined) => readonly ["iam-roles", string | undefined];
+/** Query key for one project's service-account role assignments — shared with
+ *  {@link fetchProjectAgentAssignments} so an early prefetch (e.g.
+ *  `access-projects-tab.tsx`, which knows `accountId`/`projectId` long before
+ *  `ProjectAgentAccessList` mounts) lands in the exact cache slot this hook
+ *  reads, instead of a second request under a slightly different key. */
+export declare const projectAgentAssignmentsQueryKey: (accountId: string | undefined, projectId: string) => readonly ["iam-assignments", string | undefined, "service_account", string];
+/** The two-request merge behind {@link useProjectAgentAssignments}, factored
+ *  out so a prefetch can call the SAME fetch — not a hand-copied duplicate
+ *  that silently drifts from the filter below. */
+export declare function fetchProjectAgentAssignments(accountId: string, projectId: string): Promise<RoleAssignment[]>;
+/** Every service-account role assignment in one project. Admin-only. */
+export declare function useProjectAgentAssignments(accountId: string | undefined, projectId: string, enabled?: boolean): import("@tanstack/react-query").UseQueryResult<RoleAssignment[], Error>;
+export type AgentCeilingState = {
+    kind: 'loading';
+}
+/** The viewer may not read IAM. The ceiling exists; it is not theirs to see. */
+ | {
+    kind: 'hidden';
+} | {
+    kind: 'default';
+} | {
+    kind: 'roles';
+    roleKeys: string[];
+    actions: string[];
+};
+export interface AgentAuthorityState {
+    ceiling: AgentCeilingState;
+    identity: AgentIdentity | null;
+    authority: AgentAuthority;
+}
+/** The whole agent-authority read for one agent: ceiling and intersection.
+ *
+ *  There is no project switch for this model. Enforcement stays server-side
+ *  (`apps/api/src/iam/agent-principal.ts`). */
+export declare function useAgentAuthority({ projectId, accountId, agentName, grant, }: {
+    projectId: string;
+    accountId: string | undefined;
+    agentName: string;
+    grant: PermissionGrant;
+}): AgentAuthorityState;