@danxbot/ui 1.0.0

package/dist/types/components/drag-drop/shift.d.ts

@@ -0,0 +1,66 @@
+import type { ContainerId, DragAxis, DragState, LayoutSnapshot } from "../../lib/dnd";
+export interface ContainerShift {
+    axis: DragAxis;
+    /** Items in this container with the carried one removed. */
+    restCount: number;
+    /**
+     * The carried item's extent along the axis — the size of the hole that opens.
+     * The step neighbours move by is this PLUS the spacing between two items,
+     * because the arriving item brings its own gap with it.
+     */
+    gapSize: number;
+    /** `gapSize` plus the measured spacing: how far one neighbour moves. */
+    step: number;
+    /** Measured spacing between two adjacent items of this container. */
+    spacing: number;
+    /** Insertion index in this container, or null when it is not the target. */
+    markerAt: number | null;
+    /** Displacement along the axis, in px, for the rest item at `restIndex`. */
+    itemShift: (restIndex: number) => number;
+    /**
+     * Displacement for the insertion marker rendered before rest item
+     * `restIndex` — or at `restCount`, meaning after every item.
+     *
+     * The marker takes ONLY the home-slot half. It IS the gap, so applying the
+     * gap displacement to it would move it out of the space it marks.
+     */
+    markerShift: (restIndex: number) => number;
+}
+/**
+ * Everything one container needs to render the shift, or null when no drag is
+ * in flight and nothing should move.
+ *
+ * `lifted` says whether something else is carrying the card — a
+ * `<DragDropOverlay>` is mounted. It decides ONLY whether the home slot closes,
+ * and the reason is not cosmetic: with no overlay the card is still sitting in
+ * its own slot, so closing that slot slides a neighbour underneath it.
+ */
+export declare function containerShift(layout: LayoutSnapshot | null, state: DragState, container: ContainerId, lifted: boolean): ContainerShift | null;
+/** A rect in viewport coordinates. */
+export interface GapRect {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
+/**
+ * Where the opened gap sits on screen, for a carried card that has no pointer
+ * to follow.
+ *
+ * Viewport coordinates, taken from the same snapshot the shift is computed
+ * from, so the two cannot disagree about where the hole is. The snapshot is
+ * re-taken whenever the keyboard insertion point moves out of view
+ * (`autoscroll.ts#keepKeyboardTargetVisible`), which is the only thing that
+ * moves these boxes during a keyboard drag.
+ */
+export declare function gapRect(layout: LayoutSnapshot | null, state: DragState, lifted: boolean): GapRect | null;
+/**
+ * The shift as an inline style.
+ *
+ * `translate` rather than `transform`, so a component can still rotate or scale
+ * the same element without the two having to be composed into one string — the
+ * floating clone does exactly that.
+ */
+export declare function shiftStyle(axis: DragAxis, distance: number): {
+    translate: string;
+};

package/dist/types/components/markdown/Affordances.d.ts

@@ -0,0 +1,76 @@
+import { type BlockInfo, type BlockKind, type ConstructInfo } from "../../lib/markdown/convert";
+import { type Command } from "../../lib/markdown/commands";
+import type { MarkdownSurface } from "../../lib/markdown/surface";
+export interface EditorState {
+    source: string;
+    /** Collapsed caret offset, or null when there is no selection in the host. */
+    caret: number | null;
+    /** True when the selection covers something. */
+    ranged: boolean;
+    block: BlockInfo | null;
+    construct: ConstructInfo | null;
+}
+/**
+ * Tracks source and selection, and derives what is under the caret.
+ *
+ * `selectionchange` is a DOCUMENT event and the only signal for a caret the
+ * browser moved on its own — a click, a drag, an arrow key. It fires for the
+ * surface's own restore too, which is harmless here because this only reads.
+ */
+export declare function useEditorState(surface: MarkdownSurface | null, version: number): EditorState;
+interface TypeChoice {
+    kind: BlockKind;
+    level?: number;
+    label: string;
+    icon: string;
+}
+export interface LineHandleProps {
+    surface: MarkdownSurface | null;
+    state: EditorState;
+    run: (command: Command) => void;
+    /** The container the handle is positioned inside. */
+    container: HTMLElement | null;
+}
+/**
+ * A type control beside the line under the pointer, or under the caret.
+ *
+ * ON HOVER AND ON THE CARET'S LINE, never on every line at once: a permanent
+ * gutter of forty identical buttons is noise, and one that follows the pointer
+ * is discoverable the moment a pointer moves. The caret's line is included so
+ * the control exists for someone who is not using a pointer at all.
+ */
+export declare function LineHandle({ surface, state, run, container }: LineHandleProps): import("react").JSX.Element | null;
+export interface ConstructBarProps {
+    surface: MarkdownSurface | null;
+    state: EditorState;
+    run: (command: Command) => void;
+    container: HTMLElement | null;
+}
+/**
+ * The controls for whatever the caret is inside — a link, an image, a fence or
+ * a table.
+ *
+ * IT APPEARS BY ITSELF rather than waiting for a click, and that is a decision
+ * the always-hidden markup forces. A destination the caret cannot enter and a
+ * control that has to be found are the same thing as no control at all; a small
+ * bar anchored to the construct you are already standing in is the shortest
+ * path from "I want to change this URL" to changing it.
+ */
+export declare function ConstructBar({ surface, state, run, container }: ConstructBarProps): import("react").JSX.Element | null;
+export interface ConversionMenuProps {
+    surface: MarkdownSurface | null;
+    state: EditorState;
+    run: (command: Command) => void;
+    container: HTMLElement | null;
+}
+/**
+ * Right-click conversions for a selection.
+ *
+ * OURS ONLY WHEN THERE IS SOMETHING TO CONVERT. Swallowing every right-click
+ * costs the browser's own spellcheck suggestions, which is a worse trade than
+ * this menu is worth — so with no selection and nothing under the pointer, the
+ * native menu is left alone.
+ */
+export declare function ConversionMenu({ surface, state, run, container }: ConversionMenuProps): import("react").JSX.Element | null;
+export declare const AFFORDANCE_TYPES: TypeChoice[];
+export {};

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

@@ -0,0 +1,8 @@
+export interface AccountMenuProps {
+    onNavigateProfile?: () => void;
+    onNavigateRoles?: () => void;
+    onSwitchTeam?: (teamId: string) => void;
+    onSignOut?: () => void;
+    className?: string;
+}
+export declare function AccountMenu({ onNavigateProfile, onNavigateRoles, onSwitchTeam, onSignOut, className, }: AccountMenuProps): import("react").JSX.Element;

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

@@ -0,0 +1,5 @@
+export interface DevToolsPopoverProps {
+    /** Deep link to the dev-only Use Case Ledger. Omit and the row does not render. */
+    onOpenUseCaseLedger?: () => void;
+}
+export declare function DevToolsPopover({ onOpenUseCaseLedger }?: DevToolsPopoverProps): import("react").JSX.Element | null;

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

@@ -0,0 +1 @@
+export declare function ProfilePage(): import("react").JSX.Element;

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

@@ -0,0 +1,64 @@
+import { type ReactNode } from "react";
+import type { Permission, Role, Team, TeamMembership, User } from "./types";
+export interface RBACProviderProps {
+    currentUser: User;
+    roles: Role[];
+    permissions: Permission[];
+    teams: Team[];
+    /** All memberships for `currentUser`, across every team — not just the current one. */
+    memberships: TeamMembership[];
+    currentTeamId: string;
+    /**
+     * Decides who may open the Dev Tools "view as" escape hatch.
+     *
+     * Deliberately a predicate over the consumer's OWN data (`user`, `roles`,
+     * `memberships`) rather than a boolean prop or a hardcoded role check. The
+     * library has no idea what "admin enough to use dev tools" means for any
+     * given consumer — one app might key it off a role id, another off a team
+     * membership count, another off a flag on `User` this contract doesn't even
+     * define. Only the consumer's own data model can answer that, so the
+     * decision is handed back to them wholesale.
+     */
+    canAccessDevTools: (user: User, roles: Role[], memberships: TeamMembership[]) => boolean;
+    children: ReactNode;
+}
+export interface RBACHookResult {
+    actualUser: User;
+    currentTeam: Team | undefined;
+    /** The role backing `actualUser`'s own membership in `currentTeamId` — never affected by impersonation. */
+    actualRole: Role | undefined;
+    /** `null` when not impersonating. */
+    viewingAsRoleId: string | null;
+    setViewingAsRoleId: (id: string | null) => void;
+    /** `actualRole`, unless impersonating — then the impersonated role. */
+    effectiveRole: Role | undefined;
+    effectivePermissionKeys: Set<string>;
+    hasPermission: (key: string) => boolean;
+    /**
+     * Whether the REAL logged-in user may open Dev Tools.
+     *
+     * See the block comment above `evaluateCanAccessDevTools` below for why this
+     * is computed from `actualUser`/`roles`/`memberships` and can NEVER be
+     * re-derived from `effectiveRole` / `viewingAsRoleId` — that is the entire
+     * point of this field existing on the hook at all.
+     */
+    canAccessDevTools: boolean;
+    isImpersonating: boolean;
+    roles: Role[];
+    permissions: Permission[];
+    teams: Team[];
+}
+export declare function RBACProvider({ currentUser, roles, permissions, teams, memberships, currentTeamId, canAccessDevTools, children, }: RBACProviderProps): import("react").JSX.Element;
+/**
+ * Reads the RBAC context.
+ *
+ * Throws rather than returning `undefined` — the same shape as
+ * `useDragDrop` / `useDragDropContainer` (`drag-drop/context.ts`) and every
+ * other multi-part context in this library. A component that silently
+ * received `undefined` here would fail wherever it FIRST tries to read a
+ * field off the result, several lines and possibly several components away
+ * from the actual mistake (forgetting the `<RBACProvider>` wrapper) — a
+ * blank permissions list is a much harder bug to trace back than a thrown
+ * error naming the missing provider.
+ */
+export declare function useRBAC(): RBACHookResult;

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

@@ -0,0 +1,6 @@
+import type { Permission, Role } from "./types";
+export interface RolePermissionMatrixProps {
+    roles: Role[];
+    permissions: Permission[];
+}
+export declare function RolePermissionMatrix({ roles, permissions }: RolePermissionMatrixProps): import("react").JSX.Element;

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

@@ -0,0 +1 @@
+export declare function RolesPermissionsPage(): import("react").JSX.Element;

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

@@ -0,0 +1,7 @@
+export * from "./types";
+export * from "./RBACProvider";
+export * from "./AccountMenu";
+export * from "./DevToolsPopover";
+export * from "./RolePermissionMatrix";
+export * from "./ProfilePage";
+export * from "./RolesPermissionsPage";

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

@@ -0,0 +1,26 @@
+export interface Permission {
+    /** Arbitrary, consumer-defined. The library only ever compares keys for equality. */
+    key: string;
+    label: string;
+    category?: string;
+}
+export interface Role {
+    id: string;
+    label: string;
+    permissionKeys: string[];
+}
+export interface User {
+    id: string;
+    name: string;
+    email: string;
+    avatarUrl?: string;
+}
+export interface Team {
+    id: string;
+    name: string;
+}
+export interface TeamMembership {
+    userId: string;
+    teamId: string;
+    roleId: string;
+}

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,45 @@
+import { type BadgeProps } from "../Badge";
+import type { Domain, Phase, RoadmapItem, RoadmapItemStatus, UseCase, UseCaseStatus } from "./types";
+export declare const ROADMAP_ITEM_STATUS_BADGE: Record<RoadmapItemStatus, {
+    tone: BadgeProps["tone"];
+    label: string;
+    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[];
+    /** 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;
+    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, onUseCaseStatusChange, defaultExpanded, className, }: RoadmapItemCardProps): import("react").JSX.Element;

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

@@ -0,0 +1,9 @@
+import type { Domain, Phase, RoadmapItem, UseCase } from "./types";
+export interface RoadmapPageProps {
+    domains: Domain[];
+    phases: Phase[];
+    items: RoadmapItem[];
+    useCases: UseCase[];
+    className?: string;
+}
+export declare function RoadmapPage({ domains, phases, items, useCases, className }: RoadmapPageProps): import("react").JSX.Element;

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

@@ -0,0 +1,9 @@
+import type { Domain, Phase, RoadmapItem, UseCase } from "./types";
+export interface RoadmapSwimlaneBoardProps {
+    domains: Domain[];
+    phases: Phase[];
+    items: RoadmapItem[];
+    useCases: UseCase[];
+    className?: string;
+}
+export declare function RoadmapSwimlaneBoard({ domains, phases, items, useCases, className, }: RoadmapSwimlaneBoardProps): import("react").JSX.Element;

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

@@ -0,0 +1,14 @@
+import type { UseCase, UseCaseStatus } from "./types";
+export interface UseCaseCardProps {
+    useCase: UseCase;
+    /**
+     * 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;
+    className?: string;
+}
+export declare function UseCaseCard({ useCase, onStatusChange, className }: UseCaseCardProps): import("react").JSX.Element;

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

@@ -0,0 +1,21 @@
+import type { Domain, Phase, RoadmapItem, UseCase, UseCaseStatus } from "./types";
+export interface UseCaseLedgerPageProps {
+    domains: Domain[];
+    phases: Phase[];
+    items: RoadmapItem[];
+    useCases: UseCase[];
+    /** 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;
+    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, onUseCaseStatusChange, 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,12 @@
+import type { RoadmapItemStatus, UseCase } from "./types";
+/**
+ * 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.
+ */
+export declare function deriveRoadmapItemStatus(useCases: UseCase[]): RoadmapItemStatus;

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

@@ -0,0 +1,9 @@
+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";

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

@@ -0,0 +1,54 @@
+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;
+}
+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;
+    /** Claude-managed. */
+    implemented: boolean;
+    implementedNote?: string;
+    /** Append-only decision log — caveats, reversals, "why it landed here". */
+    decisions?: UseCaseDecision[];
+}