@50arms/ui 0.0.0-stage → 35.2.0

package/dist/types/components/rbac/SessionsList.d.ts

@@ -0,0 +1,35 @@
+import type { ReactNode } from "react";
+import { type EndedState, type IdleState } from "./EndedLine";
+export interface Session {
+    id: number;
+    /** A human label for the session — "Chrome on macOS", "iPhone app", whatever
+     *  the consumer's own backend derives from the user agent. */
+    name: string;
+    /** ISO instant. */
+    createdAt: string;
+    /** ISO instant. */
+    lastUsedAt: string;
+    /** ISO instant, or `null`/omitted for a session with no expiry. */
+    expiresAt?: string | null;
+    userAgent?: string;
+    ip?: string;
+    /** True for exactly one row — the session this UI is currently running in. */
+    current: boolean;
+    /** DX-5246: set on a session that has ended (signed out, revoked or expired): the consumer's own words for how it ended (`label`) and the ISO instant it did (`at`). An ended row shows them under its name and offers no revoke. */
+    ended?: EndedState;
+    /** DX-5246: set on a session that still works but nobody is using (idle): the consumer's own words (`label`) and the ISO instant it was last in use (`at`). An idle row shows them under its name and keeps its revoke. */
+    idle?: IdleState;
+    /** DX-5247: the id of the browser the session was made in, a debugging label. Shown (first 9 characters) with a copy control in the Browser column; the whole id is what is copied. Omit for a session that has none: the cell reads "—". */
+    browserId?: string;
+    /** DX-5247: true on every row whose `browserId` is the browser this UI is running in: it gets a "This browser" badge and a tinted row. */
+    thisBrowser?: boolean;
+}
+export interface SessionsListProps {
+    sessions: Session[];
+    onRevoke: (id: number) => Promise<void>;
+    /** The id of a session currently mid-revoke. Disables just that row. */
+    busyId?: number | null;
+    emptyState?: ReactNode;
+    className?: string;
+}
+export declare function SessionsList({ sessions, onRevoke, busyId, emptyState, className }: SessionsListProps): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined>;

package/dist/types/components/rbac/TeamSettingsForm.d.ts

@@ -0,0 +1,22 @@
+export interface TeamSettingsFormTeam {
+    name: string;
+    logoUrl?: string | null;
+}
+export interface TeamSettingsFormSaveInput {
+    name: string;
+    /** Present only when the logo changed: a URL sets it, `null` removes it. */
+    logoUrl?: string | null;
+}
+export interface TeamSettingsFormProps {
+    team: TeamSettingsFormTeam;
+    onSave: (input: TeamSettingsFormSaveInput) => Promise<void>;
+    /** Uploads the file to storage and resolves with its URL. Must NOT change the
+     *  team record — the logo is only persisted by `onSave`. */
+    onUploadLogo: (file: File) => Promise<string>;
+    /** The viewer lacks `team.update` — every control renders disabled. */
+    readOnly?: boolean;
+    saveLabel?: string;
+    discardLabel?: string;
+    className?: string;
+}
+export declare function TeamSettingsForm({ team, onSave, onUploadLogo, readOnly, saveLabel, discardLabel, className, }: TeamSettingsFormProps): import("react").JSX.Element;

package/dist/types/components/rbac/TeamSwitcher.d.ts

@@ -0,0 +1,5 @@
+export interface TeamSwitcherProps {
+    onSwitchTeam?: (teamId: string) => void;
+    className?: string;
+}
+export declare function TeamSwitcher({ onSwitchTeam, className }: TeamSwitcherProps): import("react").JSX.Element | null;

package/dist/types/components/rbac/approvalPanelParts.d.ts

@@ -0,0 +1,69 @@
+import { type ReactNode } from "react";
+export type AccessRequestState = "pending" | "approved" | "denied" | "expired" | "claimed";
+/** Why a request expired and what its requester does next, in the consumer's words; the Expired readout leads with them. */
+export interface ExpiredNote {
+    /** Why the request is over, e.g. "The agent's session ended.". */
+    reason: string;
+    /** What the requester must do to get access, e.g. "The agent must reconnect and ask again.". */
+    nextStep: string;
+}
+export declare function ApprovalHeader({ title, state, revokedLabel }: {
+    title: string;
+    state: AccessRequestState;
+    revokedLabel?: string;
+}): import("react").JSX.Element;
+/** The code is for comparing, never copying: plain large text, no copy control (see `AccessRequestPanel`). */
+export declare function ConfirmCodeCallout({ code }: {
+    code: string;
+}): import("react").JSX.Element;
+/** A typed confirm code is compared in upper case with every space removed; dashes are part of the code. */
+export declare function normalizeConfirmCode(value: string): string;
+/** True when what was typed is the expected code, in either case and ignoring spaces. */
+export declare function confirmCodeMatches(typed: string, expected: string): boolean;
+/**
+ * The entry step for a confirm code (DX-4467): the approver types the code the requester shows instead of reading it
+ * off this screen, so the code is never rendered here and cannot be copied from the page.
+ */
+export declare function ConfirmCodeEntry({ expected, value, onValueChange }: {
+    expected: string;
+    value: string;
+    onValueChange: (next: string) => void;
+}): import("react").JSX.Element;
+/** The readout for a settled request: the tone and title are shared, the sentence says what it meant for this requester. */
+export declare function TerminalCallout({ state, children }: {
+    state: Exclude<AccessRequestState, "pending">;
+    children: ReactNode;
+}): import("react").JSX.Element;
+type ApprovalAction = "approve" | "deny";
+/**
+ * Busy / error state around the two decisions. A rejected promise shows its message and re-enables the buttons; a
+ * resolved one leaves the panel as it was, because `state` is the consumer's server's answer, never assumed here.
+ */
+export declare function useApprovalActions(): {
+    busy: ApprovalAction | null;
+    error: {
+        action: ApprovalAction;
+        message: string;
+    } | null;
+    run: (action: ApprovalAction, call: () => Promise<void>) => Promise<void>;
+};
+export declare function ApprovalError({ error }: {
+    error: {
+        action: ApprovalAction;
+        message: string;
+    } | null;
+}): import("react").JSX.Element | null;
+export declare function ApprovalButtons({ busy, run, onApprove, onDeny, approveDisabled, }: {
+    busy: ApprovalAction | null;
+    run: (action: ApprovalAction, call: () => Promise<void>) => Promise<void>;
+    onApprove: () => Promise<void>;
+    onDeny: () => Promise<void>;
+    /** True when there is nothing valid to approve. Deny is never disabled by this. */
+    approveDisabled: boolean;
+}): import("react").JSX.Element;
+/** The Expired readout: with a note it names the cause and the requester's next step, without one it only says nothing was granted. */
+export declare function ExpiredNotice({ note, fallback }: {
+    note: ExpiredNote | undefined;
+    fallback: string;
+}): import("react").JSX.Element;
+export {};

package/dist/types/components/rbac/index.d.ts

@@ -0,0 +1,25 @@
+export * from "./types";
+export * from "./RBACProvider";
+export * from "./Can";
+export * from "./AccountMenu";
+export * from "./TeamSwitcher";
+export * from "./DevToolsPopover";
+export * from "./RolePermissionMatrix";
+export * from "./RoleEditorDialog";
+export * from "./ProfileForm";
+export * from "./ProfilePage";
+export * from "./RolesPermissionsPage";
+export * from "./MembersPanel";
+export * from "./ChangePasswordForm";
+export * from "./SessionsList";
+export * from "./RoleKeyPicker";
+export type { ApiKey, KeyGrant, KeyRoleEditor } from "./ApiKeysTable";
+export * from "./ApiKeysPanel";
+export * from "./AgentKeysList";
+export * from "./AccessRequestPanel";
+export * from "./PermissionRequestPanel";
+export * from "./InvitationsList";
+export * from "./InviteMembersDialog";
+export * from "./Brand";
+export * from "./TeamSettingsForm";
+export * from "./DangerZone";

package/dist/types/components/rbac/permissionSections.d.ts

@@ -0,0 +1,8 @@
+import type { Permission } from "./types";
+export interface PermissionSection {
+    /** `undefined` when nothing in this matrix carries a `category` — see below. */
+    label: string | undefined;
+    items: Permission[];
+}
+/** Buckets permissions by `category` (the grouping rule is `groupInOrder`'s, shared with `ToggleMatrix`). */
+export declare function groupByCategory(permissions: Permission[], otherLabel: string): PermissionSection[];

package/dist/types/components/rbac/stagedForm.d.ts

@@ -0,0 +1,25 @@
+export interface SaveFlow {
+    saving: boolean;
+    /** The last Save resolved and nothing has been edited since. */
+    saved: boolean;
+    error: string | null;
+    /** Run a draft change (an edit, or a Discard) and retire the last outcome. */
+    edit: (change: () => void) => void;
+    /** Run the consumer's `onSave`; a rejection's message (or `failureMessage`) becomes `error`. */
+    save: (run: () => Promise<void>) => Promise<void>;
+}
+export declare function useSaveFlow(failureMessage: string): SaveFlow;
+export interface StagedFormActionsProps {
+    onSave: () => void;
+    onDiscard: () => void;
+    /** The draft is valid, changed, and nothing is in flight. */
+    canSave: boolean;
+    /** The draft differs from what is saved in ANY way, including whitespace Save would trim away. */
+    canDiscard: boolean;
+    saving: boolean;
+    /** The Save button's text; omit for the built-in one. */
+    saveLabel?: string;
+    /** The Discard button's text; omit for the built-in one. */
+    discardLabel?: string;
+}
+export declare function StagedFormActions({ onSave, onDiscard, canSave, canDiscard, saving, saveLabel, discardLabel, }: StagedFormActionsProps): import("react").JSX.Element;

package/dist/types/components/rbac/types.d.ts

@@ -0,0 +1,65 @@
+export interface Permission {
+    /** Arbitrary, consumer-defined. The library only ever compares keys for equality. */
+    key: string;
+    label: string;
+    category?: string;
+    /** Longer prose for a permission-matrix cell or a "what does this grant"
+     *  tooltip. Optional — a consumer with nothing more to say than `label`
+     *  omits it and every reader (`RolePermissionMatrix`, `AccountMenu`) falls
+     *  back to `label` alone, exactly as before this field existed. */
+    description?: string;
+    /** DXUI-29 — present: no role's cell for this permission can be toggled,
+     *  even in an editable matrix (a consumer's rules say who may change it);
+     *  the text names why, on the lock beside the permission's label. */
+    lockedReason?: string;
+}
+export interface Role {
+    id: string;
+    label: string;
+    permissionKeys: string[];
+    /** Longer prose about what this role is for. Optional, same fallback rule
+     *  as `Permission.description`. */
+    description?: string;
+    /** True for a role the consumer seeds rather than a person authors — the
+     *  library draws no behavior from this beyond what a consumer's own UI
+     *  (a "System" badge, a disabled rename field) chooses to key off it. */
+    system?: boolean;
+    /** True for a role a consumer's own rules forbid editing or deleting
+     *  outright (the immutable "every permission, always" role a system tends
+     *  to keep one of). Distinct from `system`: a system role can still be
+     *  editable (its permission set changed, even reset to default), while a
+     *  locked role cannot be touched at all. Never derived here — the library
+     *  has no opinion on which role, if any, deserves this. */
+    locked?: boolean;
+    /** `false` hides the Delete control for this role in `RolesPermissionsPage`'s
+     *  manage-roles list, while leaving rename/reset available. For a role the
+     *  consumer's own backend refuses to delete outright (distinct from
+     *  `locked`, which hides the whole row) — e.g. danxbot's system AGENT
+     *  roles, which stay editable/resettable but can never be removed.
+     *  Omitted or `true` means deletable, matching every `Role` from before
+     *  this field existed. */
+    deletable?: boolean;
+}
+export interface User {
+    id: string;
+    name: string;
+    email: string;
+    avatarUrl?: string;
+    /** A stable handle distinct from the display `name`, when a consumer's
+     *  account model has one (sign-in identifier, `@handle`). Optional — a
+     *  consumer with no separate concept of a username omits it. */
+    username?: string;
+}
+export interface Team {
+    id: string;
+    name: string;
+    /** The team's own brand mark, when it has uploaded one. `undefined`
+     *  (never `null`) is "no logo set" — the same optional-field convention
+     *  every other field on this type already uses. */
+    logoUrl?: string;
+}
+export interface TeamMembership {
+    userId: string;
+    teamId: string;
+    roleId: string;
+}

package/dist/types/components/rbac/useStagedImage.d.ts

@@ -0,0 +1,15 @@
+export interface StagedImage {
+    /** What to show: the staged URL (or `null` for a staged removal), else the saved one. */
+    value: string | null;
+    /** The staged value differs from the saved one — the form must send it on Save. */
+    dirty: boolean;
+    /** A pick is mid-upload. */
+    uploading: boolean;
+    /** Stage a URL, or `null` to stage a removal. */
+    stage: (url: string | null) => void;
+    /** Drop the staged value and go back to the saved one. */
+    discard: () => void;
+    /** Pass to `ImageUploadField.onUpload`. */
+    upload: (file: File) => Promise<string>;
+}
+export declare function useStagedImage(saved: string | null | undefined, onUpload: (file: File) => Promise<string>): StagedImage;

package/dist/types/components/roadmap/PhaseManager.d.ts

@@ -0,0 +1,19 @@
+import type { Phase, RoadmapItem } from "./types";
+export interface PhaseManagerProps {
+    phases: Phase[];
+    /** Read-only — used only to compute the delete guard below. */
+    roadmapItems: RoadmapItem[];
+    /** `order` is pre-computed by this component (next after the current max)
+        so the caller only has to assign an id and persist. */
+    onCreate: (phase: {
+        name: string;
+        order: number;
+    }) => void;
+    onRename: (id: string, name: string) => void;
+    /** The full phase list, reordered and renumbered (`order` === new index) —
+        the caller persists each row's new `order`, e.g. one `update` per id. */
+    onReorder: (phases: Phase[]) => void;
+    onDelete: (id: string) => void;
+    className?: string;
+}
+export declare function PhaseManager({ phases, roadmapItems, onCreate, onRename, onReorder, onDelete, className, }: PhaseManagerProps): import("react").JSX.Element;

package/dist/types/components/roadmap/RoadmapItemCard.d.ts

@@ -0,0 +1,51 @@
+import { type BadgeProps } from "../Badge";
+import type { Domain, Phase, RoadmapItem, RoadmapItemStatus, Track, UseCase, UseCaseStatus } from "./types";
+export declare const ROADMAP_ITEM_STATUS_BADGE: Record<RoadmapItemStatus, {
+    tone: BadgeProps["tone"];
+    live?: boolean;
+}>;
+export interface RoadmapItemCardProps {
+    item: RoadmapItem;
+    domain: Domain;
+    /** `domain`'s position in the FULL `domains[]` list the caller was handed —
+        computed once by the caller (`domains.findIndex(...)`, or a `.map()`
+        index), never re-derived here. Drives the domain Badge's cycling tone
+        via `toneForIndex`, the same "the card computes nothing it wasn't
+        explicitly handed" pattern already used for `useCases` below. */
+    domainIndex: number;
+    phase: Phase;
+    /** Same pattern as `domainIndex`, for `phase`. */
+    phaseIndex: number;
+    /** This item's OWN use cases (already filtered by `goalRef === item.ref`) —
+        the card computes its status from exactly this list and renders nothing
+        more, so a caller handing it the wrong slice silently mis-derives status
+        rather than the card silently re-filtering a different assumption. */
+    useCases: UseCase[];
+    /** The consumer's build tracks, in display order. Threaded straight through
+        to every `UseCaseCard`, and used for this item's own status rollup —
+        "shipped" means every live use case is verified AND built on all of them,
+        so an item cannot report shipped off a built interface alone. */
+    tracks: readonly Track[];
+    /** Forwarded to each `UseCaseCard`'s `onStatusChange` as
+        `onUseCaseStatusChange(useCase.ref, status)`. Omitted (the default,
+        `RoadmapSwimlaneBoard`'s customer-facing use) keeps every `UseCaseCard`
+        read-only — see `UseCaseCard`'s own `onStatusChange` doc. */
+    onUseCaseStatusChange?: (ref: string, status: UseCaseStatus) => void;
+    /** Same forwarding as `onUseCaseStatusChange`, for the build chips. */
+    onUseCaseBuiltChange?: (ref: string, trackId: string, built: boolean) => void;
+    defaultExpanded?: boolean;
+    className?: string;
+}
+/**
+ * A single roadmap item, expandable to reveal the use cases behind it.
+ *
+ * COLLAPSED BY DEFAULT, REVEALED BY A CLICK — this is the literal "click a
+ * roadmap item to see the use cases inside it" interaction from the product
+ * spec, not a static list that happens to render inside a card. A disclosure
+ * button (`aria-expanded` + `aria-controls`) rather than making the whole card
+ * clickable: a card-sized hit target with no visible affordance is the classic
+ * "is this a link or a label" ambiguity, and a card is also where a consumer
+ * may reasonably want to add its OWN click behaviour (e.g. deep-linking) later
+ * without fighting this one for the same element.
+ */
+export declare function RoadmapItemCard({ item, domain, domainIndex, phase, phaseIndex, useCases, tracks, onUseCaseStatusChange, onUseCaseBuiltChange, defaultExpanded, className, }: RoadmapItemCardProps): import("react").JSX.Element;

package/dist/types/components/roadmap/RoadmapPage.d.ts

@@ -0,0 +1,12 @@
+import type { Domain, Phase, RoadmapItem, Track, UseCase } from "./types";
+export interface RoadmapPageProps {
+    domains: Domain[];
+    phases: Phase[];
+    items: RoadmapItem[];
+    useCases: UseCase[];
+    /** Passed straight through — see `RoadmapSwimlaneBoard` for why the build
+        tracks stay visible on the customer-facing board. */
+    tracks: Track[];
+    className?: string;
+}
+export declare function RoadmapPage({ domains, phases, items, useCases, tracks, className, }: RoadmapPageProps): import("react").JSX.Element;

package/dist/types/components/roadmap/RoadmapSwimlaneBoard.d.ts

@@ -0,0 +1,15 @@
+import type { Domain, Phase, RoadmapItem, Track, UseCase } from "./types";
+export interface RoadmapSwimlaneBoardProps {
+    domains: Domain[];
+    phases: Phase[];
+    items: RoadmapItem[];
+    useCases: UseCase[];
+    /** The consumer's build tracks — shown on every use case here too, NOT
+        hidden from the customer-facing view. It is tempting to drop the second
+        track from a prospect's board, and it is the wrong instinct: "the
+        interface is built and the service behind it lands on this date" is a
+        stronger and more honest thing to show than a single ambiguous tick. */
+    tracks: readonly Track[];
+    className?: string;
+}
+export declare function RoadmapSwimlaneBoard({ domains, phases, items, useCases, tracks, className, }: RoadmapSwimlaneBoardProps): import("react").JSX.Element;

package/dist/types/components/roadmap/TrackManager.d.ts

@@ -0,0 +1,19 @@
+import type { Track, UseCase } from "./types";
+export interface TrackManagerProps {
+    tracks: Track[];
+    /** Read-only — used only to compute progress and the delete guard below. */
+    useCases: UseCase[];
+    /** `order` is pre-computed by this component (next after the current max)
+        so the caller only has to assign an id and persist. */
+    onCreate: (track: {
+        name: string;
+        order: number;
+    }) => void;
+    onRename: (id: string, name: string) => void;
+    /** The full track list, reordered and renumbered (`order` === new index) —
+        the caller persists each row's new `order`, e.g. one `update` per id. */
+    onReorder: (tracks: Track[]) => void;
+    onDelete: (id: string) => void;
+    className?: string;
+}
+export declare function TrackManager({ tracks, useCases, onCreate, onRename, onReorder, onDelete, className, }: TrackManagerProps): import("react").JSX.Element;

package/dist/types/components/roadmap/UseCaseCard.d.ts

@@ -0,0 +1,30 @@
+import type { Track, UseCase, UseCaseStatus } from "./types";
+export interface UseCaseCardProps {
+    useCase: UseCase;
+    /**
+     * The build tracks to report against, in display order — the consumer's own
+     * list, whatever it named them. A track absent from `useCase.built` reads as
+     * not built.
+     *
+     * Required rather than optional: a card that silently renders no build state
+     * because a caller forgot the prop is exactly the "looks finished, says
+     * nothing" failure the ledger exists to prevent.
+     */
+    tracks: readonly Track[];
+    /**
+     * Makes `status` user-settable: supplying this swaps the read-only status
+     * Badge for a `Select`. Omitted (the default) keeps the Badge — so
+     * `RoadmapPage`'s customer-facing rendering of this card, if it ever
+     * renders one directly, is never forced into an editable control just
+     * because this component knows how to be one.
+     */
+    onStatusChange?: (status: UseCaseStatus) => void;
+    /**
+     * Same opt-in shape as `onStatusChange`, for the build chips: supply it and
+     * each track chip becomes a toggle button; omit it and they stay plain
+     * badges. The customer-facing roadmap omits it.
+     */
+    onBuiltChange?: (trackId: string, built: boolean) => void;
+    className?: string;
+}
+export declare function UseCaseCard({ useCase, tracks, onStatusChange, onBuiltChange, className, }: UseCaseCardProps): import("react").JSX.Element;

package/dist/types/components/roadmap/UseCaseLedgerPage.d.ts

@@ -0,0 +1,29 @@
+import type { Domain, Phase, RoadmapItem, Track, UseCase, UseCaseStatus } from "./types";
+export interface UseCaseLedgerPageProps {
+    domains: Domain[];
+    phases: Phase[];
+    items: RoadmapItem[];
+    useCases: UseCase[];
+    /** The consumer's build tracks, in display order — every use case reports
+        against all of them, and an item is only "shipped" once each live case is
+        verified and built on every one. Mount `TrackManager` beside this page
+        to manage the list. */
+    tracks: Track[];
+    /** Forwarded to every `RoadmapItemCard` -> `UseCaseCard` on this page,
+        making every use case's status genuinely user-settable here. Omitted
+        keeps every status read-only, the same default `UseCaseCard` itself
+        carries. */
+    onUseCaseStatusChange?: (ref: string, status: UseCaseStatus) => void;
+    /** Same forwarding, for the build chips: supply it and every track chip on
+        this page becomes a toggle. Omitted keeps them read-only badges. */
+    onUseCaseBuiltChange?: (ref: string, trackId: string, built: boolean) => void;
+    className?: string;
+}
+/**
+ * Dev-facing ledger — the operator's view of EVERYTHING, unlike `RoadmapPage`
+ * which filters to `customerVisible` items only. No visibility filtering
+ * happens here on purpose: this is the surface where an internal-only item, or
+ * one still "unresolved" because a use case needs a human decision, is
+ * supposed to be visible.
+ */
+export declare function UseCaseLedgerPage({ domains, phases, items, useCases, tracks, onUseCaseStatusChange, onUseCaseBuiltChange, className, }: UseCaseLedgerPageProps): import("react").JSX.Element;

package/dist/types/components/roadmap/chip-tones.d.ts

@@ -0,0 +1,2 @@
+export declare const CATEGORY_TONES: readonly ["accent", "brand", "info", "success", "warning", "neutral"];
+export declare function toneForIndex(i: number): (typeof CATEGORY_TONES)[number];

package/dist/types/components/roadmap/derive.d.ts

@@ -0,0 +1,39 @@
+import type { RoadmapItemStatus, Track, UseCase } from "./types";
+/** Built on every track in `trackIds`. An absent key is not built. */
+export declare function isFullyBuilt(useCase: UseCase, trackIds: readonly string[]): boolean;
+/** Built on none of them. */
+export declare function isUnbuilt(useCase: UseCase, trackIds: readonly string[]): boolean;
+/**
+ * A RoadmapItem's status is derived from its own UseCases, never hand-set —
+ * the same reasoning as any parent whose state depends on its children:
+ * hand-set it and it silently drifts the moment a child changes underneath it.
+ *
+ * Rejected cases fall out of the rollup entirely — dead weight, not a blocker.
+ * A goal left with no live cases (everything rejected) is "unresolved" rather
+ * than defaulting to "planned", which would misreport a goal that needs a
+ * human decision as one that simply hasn't started.
+ *
+ * SHIPPED REQUIRES EVERY TRACK, and that is the point of tracks existing. A
+ * team building its interface ahead of its backend would otherwise roll up to
+ * "shipped" on a screen with nothing behind it — the ledger's single most
+ * damaging possible lie, because "shipped" is exactly the word people stop
+ * checking.
+ *
+ * `trackIds` is required rather than defaulted. There is no sensible default:
+ * an empty list would make `every` vacuously true and quietly restore the old
+ * one-bit behaviour under a new name, which is worse than an argument.
+ */
+export declare function deriveRoadmapItemStatus(useCases: UseCase[], trackIds: readonly string[]): RoadmapItemStatus;
+/** `Track.id`s in display order — what every rollup above wants. */
+export declare function trackIds(tracks: readonly Track[]): string[];
+/**
+ * How far a set of use cases has got along ONE track: `{ built, live }`.
+ *
+ * Counted over live cases only, for the same reason the rollup ignores them:
+ * a rejected case can never be built, so including it would cap every
+ * progress reading below 100% forever.
+ */
+export declare function trackProgress(useCases: UseCase[], trackId: string): {
+    built: number;
+    live: number;
+};

package/dist/types/components/roadmap/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./types";
+export * from "./derive";
+export * from "./chip-tones";
+export * from "./UseCaseCard";
+export * from "./RoadmapItemCard";
+export * from "./RoadmapSwimlaneBoard";
+export * from "./UseCaseLedgerPage";
+export * from "./RoadmapPage";
+export * from "./PhaseManager";
+export * from "./TrackManager";

package/dist/types/components/roadmap/types.d.ts

@@ -0,0 +1,86 @@
+export type UseCaseStatus = "pending" | "in-progress" | "verified" | "rejected";
+/** Derived, never stored — see `deriveRoadmapItemStatus` in `derive.ts`. */
+export type RoadmapItemStatus = "planned" | "in-progress" | "shipped" | "unresolved";
+export interface Domain {
+    slug: string;
+    name: string;
+    description?: string;
+}
+/**
+ * A user-managed ordering bucket for `RoadmapItem`s — "MVP", "Phase 1",
+ * "Backlog" — in the consumer's own words. No fixed vocabulary: this library
+ * ships zero opinion about what phases exist, the same as `Domain`. CRUD for
+ * this list lives in `PhaseManager`.
+ */
+export interface Phase {
+    id: string;
+    name: string;
+    /** Display/sort order — lower sorts first. */
+    order: number;
+}
+export interface RoadmapItem {
+    /** e.g. "RM-001". Monotonic, never reused — the consumer's concern to assign. */
+    ref: string;
+    title: string;
+    /** One-line, customer-safe summary — what renders on the public Roadmap card. */
+    summary?: string;
+    domainSlug: string;
+    /** The owning `Phase.id`. Required — every roadmap item belongs to exactly
+        one phase; there is no "no phase" state, the same as `domainSlug`. */
+    phaseId: string;
+    /** Gates whether this item (and its rollup status) appears on the public Roadmap. */
+    customerVisible: boolean;
+}
+/**
+ * A build track — an independent axis along which a `UseCase` can be built.
+ *
+ * WHY THIS EXISTS. "Built" is not one bit for most real products. A team that
+ * builds its interface first and the service behind it afterwards needs both
+ * states on the same card, because a screen that works against simulated data
+ * and a screen backed by a real endpoint are different claims, and collapsing
+ * them into one boolean makes the ledger say "shipped" about something with
+ * nothing behind it.
+ *
+ * Consumer-managed, exactly like `Domain` and `Phase`: this library ships no
+ * vocabulary. It does not know what "UI" or "Backend" means, only that some
+ * tracks were named and use cases were marked against them. CRUD lives in
+ * `TrackManager`.
+ *
+ * A consumer with genuinely one axis passes one track, and the ledger reads
+ * the way it always did.
+ */
+export interface Track {
+    id: string;
+    name: string;
+    /** Display/sort order — lower sorts first. */
+    order: number;
+}
+export interface UseCaseDecision {
+    timestamp: string;
+    note: string;
+}
+export interface UseCase {
+    /** e.g. "UC-001". */
+    ref: string;
+    /** The parent RoadmapItem's `ref`. */
+    goalRef: string;
+    title: string;
+    description: string;
+    /** Long-form rationale — rendered collapsed by default. */
+    background?: string;
+    /** User-managed. Verified and Rejected are the only end states. */
+    status: UseCaseStatus;
+    /**
+     * Agent-managed. Keyed by `Track.id`.
+     *
+     * AN ABSENT KEY MEANS NOT BUILT — there is no third state. A tri-state here
+     * ("built" / "not built" / "unknown") would be ambiguity this data does not
+     * actually have: nobody has ever needed to record that they do not know
+     * whether they built something.
+     */
+    built: Record<string, boolean>;
+    /** Optional per-track note — same keying as `built`. */
+    builtNotes?: Record<string, string>;
+    /** Append-only decision log — caveats, reversals, "why it landed here". */
+    decisions?: UseCaseDecision[];
+}