@dloizides/ui-access-admin 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to `@dloizides/ui-access-admin` are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
+project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-07-22
+
+Initial release. Promoted out of `kefi-web`'s organizer promoter roster, which had the
+only working implementation of scoped capability links in the fleet — and had it welded
+to a `PromoterDto`.
+
+### Added
+
+- **`AccessLinkPanel`** — mint / copy / share / revoke a scoped capability link for one
+  subject. Scoped to a single subject on purpose: these links are bearer tokens, so a
+  screen listing every subject's live link would itself be a high-value secret.
+- **`AccountLinkPanel`** — bind a subject to its sign-in account, or unbind it. Unlinking
+  is a separate press from the picker so a mis-tap cannot detach someone from their work.
+- **`useCapabilityLinkMint`** / **`useSubjectAccountLink`** — the headless halves, for
+  hosts that want their own chrome.
+- **Expiry policy** (`capabilityExpiryDays`, `capabilityExpiryDate`, `daysUntilAnchor`) —
+  `anchorDate + tailDays`, clamped to the host API's accepted range. No code path returns
+  "never".
+- **`ACCESS_ADMIN_I18N`** — the machine-readable i18n manifest hosts bind a missing-key
+  guard to, following the `LAYOUT_I18N` / `TABLE_I18N` precedent. `accessAdminI18n.test.ts`
+  fails the build if a component resolves a raw key literal, or if the map carries an
+  unused entry.
+- **`ACCESS_ADMIN_TEST_IDS`** plus a `testIDPrefix` on both panels, so an adopting app
+  keeps its existing Playwright selectors.
+- **`useAccessAdminPalette`** — maps the host's `UiProvider` theme onto the colour roles
+  the panels need. No colour literals in the package.
+
+### Notes on the extraction
+
+- **No host domain types cross the boundary.** `AccessSubject` is `{ id, displayName }`.
+  Resolving WHICH subject an API's link row belongs to is the host's job, done once when
+  it normalizes its DTOs — which keeps a product's data-model compromise (kefi matches on
+  recipient name, because its wire format omits the binding) out of the shared filter.
+- **No API calls, no react-query.** Mint, link and unlink are injected async callbacks.
+- **A failed link-list load is never conflated with an empty one.** `linksFailed` exists
+  because "we could not load this" rendered as "this person has no live link" invites
+  minting a second live capability and hides that there is something to revoke.
+- **A refused clipboard write after a successful mint is reported as an ERROR**, not a
+  warning: the URL is readable exactly once, so a green toast over an empty clipboard
+  costs a revoke-and-re-mint.
+- `CheckboxField` was considered for extraction and deliberately **not** taken — the kit
+  already ships `FormCheckbox` in `@dloizides/ui-forms`, carrying both the `aria-checked`
+  fix and a keyboard-activation fix. Adding a third copy here would have been the bug this
+  package exists to avoid.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 dloizides
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# @dloizides/ui-access-admin
+
+Brand-agnostic React Native (RN-web) **user & access administration UI** for the
+dloizides.com shared kit.
+
+The frontend counterpart to what `Identity.Abstractions` already shares on the backend
+(`IUserManagementService`, `TenantManagedRoleSet`). It ships the two screens every
+product ends up rebuilding:
+
+- **`AccessLinkPanel`** — mint, copy, share and revoke a **scoped capability link** for
+  one subject, always with an expiry.
+- **`AccountLinkPanel`** — bind a subject to the account it signs in with, or unbind it.
+
+Promoted out of `kefi-web`, with every Kefi noun removed.
+
+---
+
+## The two rules that make it reusable
+
+**1. No host domain types in the public API.** The package knows about a `AccessSubject`
+(`{ id, displayName }`), a `CapabilityLink`, and a `LinkableAccount`. Nothing else. A
+survey respondent, a menu editor and a party promoter are all subjects.
+
+**2. No API calls.** Every write is an injected `async` callback. There is no
+`react-query` dependency and no client. You wire your own endpoints and your own cache
+invalidation.
+
+---
+
+## Install
+
+```bash
+npm install @dloizides/ui-access-admin
+```
+
+Peers: `@dloizides/ui-feedback`, `@dloizides/ui-buttons`, `@dloizides/ui-forms`,
+`@dloizides/ui-layout`, `react`, `react-native`.
+
+Mount a `UiProvider` (from `@dloizides/ui-feedback`) above these panels — it supplies both
+the theme and `t`.
+
+---
+
+## Quick start
+
+```tsx
+import { AccessLinkPanel, type CapabilityLink } from '@dloizides/ui-access-admin';
+
+<AccessLinkPanel
+  subject={{ id: promoter.externalId, displayName: promoter.name }}
+  policy={{ anchorDate: eventDate, tailDays: 14, minDays: 1, maxDays: 365 }}
+  links={links}                    // normalized to CapabilityLink by YOUR adapter
+  linksFailed={linksQuery.isError} // never conflated with "there are none"
+  mint={async ({ subject, expiresInDays }) => toCapabilityLink(
+    await createLink.mutateAsync(buildRequest(subject, expiresInDays)),
+  )}
+  describeError={(error) => FM(mutationErrorKey(error))}
+  renderLinkActions={(link) => <MyRevokeButton linkId={link.id} />}
+  onClose={close}
+  onResult={(message, tone) => setBanner({ message, tone })}
+/>
+```
+
+### The expiry policy
+
+`capabilityExpiryDays` resolves `anchorDate + tailDays`, clamped into `[minDays, maxDays]`.
+
+**There is no code path that returns "never."** A missing, unparseable or past anchor
+yields the bare tail, not an unbounded link. These URLs are bearer tokens pasted into chat
+apps; the expiry is the only thing limiting the blast radius of a forward.
+
+---
+
+## i18n — read this before adopting
+
+The package is **fallback-free**. `t` is your resolver, and a missing key renders the raw
+dotted name to the user.
+
+`ACCESS_ADMIN_I18N` is a machine-readable manifest of every key the package resolves.
+**Bind your missing-key guard to it**, the way `kefi-web/src/localization/kitTranslationKeys.ts`
+already binds `LAYOUT_I18N` and `TABLE_I18N`:
+
+```ts
+import { ACCESS_ADMIN_I18N } from '@dloizides/ui-access-admin';
+
+const ACCESS_ADMIN_KEYS: readonly string[] = Object.values(ACCESS_ADMIN_I18N);
+```
+
+Then an upgrade that adds a string **fails your test suite** instead of shipping raw key
+text. `accessAdminI18n.test.ts` keeps the manifest itself honest: it fails if any component
+resolves a raw literal, and if the map carries an entry nothing uses.
+
+The package owns the key **names**; you own the **wording**. That split is what lets one
+product keep warm, specific copy under a key another product reuses with its own.
+
+Every key is namespaced under `accessAdmin.*`, so it drops into a locale file as one block.
+
+---
+
+## testIDs
+
+Both panels take a `testIDPrefix`; every child derives from it. Adopting apps already have
+Playwright selectors, and a shared component is not a good enough reason to rewrite an E2E
+suite.
+
+---
+
+## Theming
+
+Colours come from your `UiProvider` theme (`@dloizides/design-tokens`). The package defines
+**no colour literals** — `useAccessAdminPalette` maps the theme onto the roles the panels
+need, so a rebrand reaches them for free.
+
+---
+
+## API
+
+| Export | What it is |
+|---|---|
+| `AccessLinkPanel` | The capability-link panel for one subject |
+| `AccountLinkPanel` | The account picker for one subject |
+| `useCapabilityLinkMint` | Mint-and-copy state (headless) |
+| `useSubjectAccountLink` | Selection + submit state for account linking (headless) |
+| `capabilityExpiryDays` / `capabilityExpiryDate` / `daysUntilAnchor` | The expiry policy |
+| `linksForSubject` / `activeLinksForSubject` / `formatLinkDate` | Pure link helpers |
+| `buildCapabilityLinkMailto` | `mailto:` compose URL (no recipient — see the source) |
+| `buildAccountOptions` / `accountDisplayLabel` | Pure picker helpers |
+| `useAccessAdminPalette` | Theme → colour roles |
+| `ACCESS_ADMIN_I18N` / `ACCESS_ADMIN_TEST_IDS` | The host contracts |
+| `AccessResultTone` | `Success` \| `Error` |
+
+---
+
+## License
+
+MIT