@50arms/ui 0.0.0-stage → 35.2.0

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

@@ -0,0 +1,154 @@
+import type { ReactNode, Ref } from "react";
+import { type VariantProps } from "tailwind-variants";
+declare const avatar: import("tailwind-variants").TVReturnType<{
+    size: {
+        xs: {
+            root: string;
+            fallback: string;
+            status: string;
+        };
+        sm: {
+            root: string;
+            fallback: string;
+            status: string;
+        };
+        md: {
+            root: string;
+            fallback: string;
+            status: string;
+        };
+        lg: {
+            root: string;
+            fallback: string;
+            status: string;
+        };
+        xl: {
+            root: string;
+            fallback: string;
+            status: string;
+        };
+    };
+    shape: {
+        circle: {
+            root: string;
+        };
+        rounded: {
+            root: string;
+        };
+    };
+}, {
+    root: string[];
+    image: string;
+    fallback: string;
+    status: string[];
+}, undefined, {
+    size: {
+        xs: {
+            root: string;
+            fallback: string;
+            status: string;
+        };
+        sm: {
+            root: string;
+            fallback: string;
+            status: string;
+        };
+        md: {
+            root: string;
+            fallback: string;
+            status: string;
+        };
+        lg: {
+            root: string;
+            fallback: string;
+            status: string;
+        };
+        xl: {
+            root: string;
+            fallback: string;
+            status: string;
+        };
+    };
+    shape: {
+        circle: {
+            root: string;
+        };
+        rounded: {
+            root: string;
+        };
+    };
+}, {
+    root: string[];
+    image: string;
+    fallback: string;
+    status: string[];
+}, import("tailwind-variants").TVReturnTypeLike<{
+    size: {
+        xs: {
+            root: string;
+            fallback: string;
+            status: string;
+        };
+        sm: {
+            root: string;
+            fallback: string;
+            status: string;
+        };
+        md: {
+            root: string;
+            fallback: string;
+            status: string;
+        };
+        lg: {
+            root: string;
+            fallback: string;
+            status: string;
+        };
+        xl: {
+            root: string;
+            fallback: string;
+            status: string;
+        };
+    };
+    shape: {
+        circle: {
+            root: string;
+        };
+        rounded: {
+            root: string;
+        };
+    };
+}, {
+    root: string[];
+    image: string;
+    fallback: string;
+    status: string[];
+}>>;
+export type AvatarStatus = "online" | "busy" | "away" | "offline";
+export interface AvatarProps extends VariantProps<typeof avatar> {
+    src?: string;
+    /** Drives the initials, the fallback tint, and the accessible name. */
+    name: string;
+    /** Overrides the derived initials — for an icon, or a custom mark. */
+    fallback?: ReactNode;
+    status?: AvatarStatus;
+    className?: string;
+    ref?: Ref<HTMLSpanElement>;
+}
+export declare function Avatar({ src, name, fallback, status, size, shape, className, ref }: AvatarProps): import("react").JSX.Element;
+export interface AvatarGroupProps {
+    children: ReactNode;
+    /** Show at most this many, then a +N chip. */
+    max?: number;
+    size?: VariantProps<typeof avatar>["size"];
+    className?: string;
+}
+/**
+ * Overlapping avatars with an overflow count.
+ *
+ * The stack order is REVERSED so earlier avatars sit on top of later ones.
+ * Left-to-right overlap with natural order puts each avatar's face under its
+ * neighbour, which is exactly the half you need to see.
+ */
+export declare function AvatarGroup({ children, max, size, className }: AvatarGroupProps): import("react").JSX.Element;
+export {};

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

@@ -0,0 +1,131 @@
+import type { HTMLAttributes, ReactNode, Ref } from "react";
+import { type VariantProps } from "tailwind-variants";
+/**
+ * The text colour of each tone, by itself: the badge's own, and the tint of an icon that wears a badge's tone without being a badge
+ * (`FilterMenu`'s option icons, DX-5374). One map so a tone is the same colour wherever it is drawn.
+ */
+export declare const BADGE_TONE_TEXT: {
+    readonly neutral: "text-secondary";
+    readonly accent: "text-accent-text";
+    readonly brand: "text-brand-text";
+    readonly success: "text-success-text";
+    readonly warning: "text-warning-text";
+    readonly danger: "text-danger-text";
+    readonly orange: "text-orange-text";
+    readonly info: "text-info-text";
+    readonly muted: "text-muted-text";
+};
+/** The neutral tone's border, wash and text as one class string (DX-6445), for a component that draws a neutral-badge look without being a `Badge` (`IconButton`'s gray comment count). Pair it with a `border` width. */
+export declare const BADGE_NEUTRAL_TONE: string;
+declare const badge: import("tailwind-variants").TVReturnType<{
+    tone: {
+        neutral: string;
+        accent: string[];
+        brand: string[];
+        success: string[];
+        warning: string[];
+        danger: string[];
+        orange: string[];
+        info: string[];
+        muted: string[];
+    };
+    size: {
+        sm: "h-5 rounded-sm px-1.5 text-2xs";
+        md: "h-6 rounded-md px-2 text-xs";
+        lg: "h-7 rounded-md px-2.5 text-sm";
+    };
+    dot: {
+        true: "";
+        false: "";
+    };
+}, undefined, string[], {
+    tone: {
+        neutral: string;
+        accent: string[];
+        brand: string[];
+        success: string[];
+        warning: string[];
+        danger: string[];
+        orange: string[];
+        info: string[];
+        muted: string[];
+    };
+    size: {
+        sm: "h-5 rounded-sm px-1.5 text-2xs";
+        md: "h-6 rounded-md px-2 text-xs";
+        lg: "h-7 rounded-md px-2.5 text-sm";
+    };
+    dot: {
+        true: "";
+        false: "";
+    };
+}, undefined, import("tailwind-variants").TVReturnTypeLike<{
+    tone: {
+        neutral: string;
+        accent: string[];
+        brand: string[];
+        success: string[];
+        warning: string[];
+        danger: string[];
+        orange: string[];
+        info: string[];
+        muted: string[];
+    };
+    size: {
+        sm: "h-5 rounded-sm px-1.5 text-2xs";
+        md: "h-6 rounded-md px-2 text-xs";
+        lg: "h-7 rounded-md px-2.5 text-sm";
+    };
+    dot: {
+        true: "";
+        false: "";
+    };
+}, undefined>>;
+/**
+ * What a badge needs in order to be removable, in one object.
+ *
+ * ONE PROP RATHER THAN TWO, and the label being a required FIELD is the point:
+ * a dismiss control with no accessible name is not expressible. An icon carries
+ * no text, and a row of filter chips is exactly where "Remove" spoken five
+ * times distinguishes nothing — the same argument that makes `IconButton.label`
+ * required. `SettingRow`'s `readOnly: { reason }` uses the same shape for the
+ * same reason: an explanation that is part of the type cannot be forgotten.
+ *
+ * Name what it removes ("Remove the infra filter"), not the picture ("Close").
+ */
+export interface BadgeDismiss {
+    label: string;
+    onDismiss: () => void;
+}
+export interface BadgeProps extends HTMLAttributes<HTMLSpanElement>, VariantProps<typeof badge> {
+    icon?: ReactNode;
+    /**
+     * DX-5143 - a CSS colour (hex, `rgb()`, `oklch()`, a `var()`) the badge is drawn in, for a colour the consuming app lets a person
+     * choose (a board list's colour) and so cannot be one of the fixed `tone`s. The border, wash and text are all derived from it,
+     * the text pulled toward the primary text colour so a pale colour stays legible on a light theme. It replaces `tone`'s colours;
+     * pass one or the other, never both.
+     */
+    color?: string;
+    /**
+     * Makes the badge a chip you can take off — a trailing × after the label.
+     *
+     * Absent means a plain label, which is what every existing badge is: an ×
+     * nobody asked for is a destructive control appearing inside a caption.
+     *
+     * NOT FOR A BADGE INSIDE A BUTTON. `StatusSelect` renders its Badge as the
+     * body of a trigger, and a `<button>` inside a `<button>` is invalid and
+     * unreachable by keyboard. A dismissible badge belongs on a surface, not in
+     * a control.
+     */
+    dismiss?: BadgeDismiss;
+    /**
+     * Ping the dot outward — for genuinely LIVE states only (running, connected,
+     * streaming). A pulse on a static label is the badge equivalent of a blinking
+     * tag: it captures attention permanently and therefore stops meaning
+     * anything.
+     */
+    pulse?: boolean;
+    ref?: Ref<HTMLSpanElement>;
+}
+export declare function Badge({ className, tone, size, dot, icon, pulse, dismiss, color, style, children, ref, ...props }: BadgeProps): import("react").JSX.Element;
+export {};

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

@@ -0,0 +1,239 @@
+import { type ReactNode } from "react";
+import type { AutoScrollOptions, CrossDrop } from "../lib/dnd";
+import type { BoardColumnModel, BoardItemId, BoardReorderLabels, UseBoardOptions, UseBoardResult } from "../lib/board";
+export interface BoardProps<T> extends UseBoardOptions<T> {
+    /**
+     * DX-4575: the words for each card menu's two within-column items. Partial,
+     * so a consumer renames one and keeps the other. Omitted, the provider's
+     * `board.moveToTop` and `board.moveToBottom`.
+     */
+    reorderLabels?: Partial<BoardReorderLabels>;
+    /**
+     * DX-4583: what dropping a card on ANOTHER lane means.
+     *
+     * `"position"` (the default) is a drop at a place: the lane's cards part, a
+     * marker shows the slot, and the `BoardMove` carries that `index`.
+     *
+     * `"lane"` is a lane change and nothing else, for a board whose lanes are
+     * ordered by something a drop cannot set (a rank the card already has): the
+     * whole lane is highlighted, no marker shows and no card moves, and the
+     * `BoardMove` is `{ columnId, lane: true }` with no position. The card menu's
+     * "Move to <lane>" items send the same move, and the live region says the lane
+     * rather than a position. Inside the card's own lane a drag is still a
+     * positional drop either way. Whether a drag is over "another lane" is read
+     * from the drag session's own `from.container` and `over.container`, never
+     * from card counts.
+     */
+    crossLaneDrop?: CrossDrop;
+    /** Forwarded to `DragDrop` — see its own doc; cannot be turned off. */
+    autoScroll?: AutoScrollOptions;
+    className?: string;
+    /**
+     * Applied to the row the columns lay out in, NOT to the board root that
+     * `className` targets.
+     *
+     * Two seams rather than one because the two boxes take genuinely different
+     * decisions: the root is where a consumer sets the board's own size and
+     * chrome, and this row is where the columns' overflow behaviour lives —
+     * horizontal scroll on a wide board, wrapping on a narrow one. The first
+     * real consumer of this component hit the gap immediately and had to reach
+     * `overflow-x-auto` onto the root, which is the wrong box: it scrolls the
+     * live region and the instructions along with the columns.
+     */
+    columnsClassName?: string;
+    /**
+     * The card while it is being carried. Defaults to the card's own children.
+     *
+     * The default is the version that cannot drift from the row it stands for,
+     * which is why it is the default. But a carried card is read at a glance
+     * while it moves, and a dense resting card is the wrong thing to read that
+     * way — the two or three fields that identify the record are all anybody
+     * takes off it mid-drag.
+     *
+     * It changes what the carried card SHOWS and nothing else. Whether a card is
+     * carried, and how, is not a board's decision: the engine lifts every dragged
+     * card into a portalled clone either way.
+     */
+    renderDragging?: (item: T) => ReactNode;
+    /** The rendered board, given the live model to map over — same shape
+     *  `DragDropOverlay`'s own `children` already uses in this package for the
+     *  identical reason: `Board` is generic over the consumer's item type, and
+     *  a render prop is how that generic reaches the consumer's JSX without a
+     *  second, parallel context API duplicating what `useBoard` already
+     *  returns. */
+    children: (board: UseBoardResult<T>) => ReactNode;
+}
+export declare function Board<T>({ items, columns, accessors, validateMove, onMove, selection, reorderLabels, crossLaneDrop, autoScroll, className, columnsClassName, renderDragging, children, }: BoardProps<T>): import("react").JSX.Element;
+export interface BoardCardSurfaceProps {
+    className?: string;
+    children?: ReactNode;
+}
+/**
+ * Makes the WHOLE card a drag source, instead of the grip alone.
+ *
+ * RENDERING IT IS WHAT TURNS IT ON — there is no `wholeCardDrag` boolean, the
+ * same rule the rest of this package follows and `drag-drop.test.tsx` enforces
+ * on its own component layer. A board that wants a grip renders no surface; a
+ * board that wants the card to drag wraps its content in one.
+ *
+ * WHY THIS IS SAFE HERE, and it was not safe before. The obvious objection is
+ * that a card usually opens something when clicked, and a card that is entirely
+ * a drag handle swallows that click. True of a source that starts on
+ * `pointerdown`; false of this engine, which holds a press in `pending` until
+ * it passes an activation constraint — 5px of travel for a mouse, a 250ms dwell
+ * for a finger. A press that does not move is still a click. A press that does
+ * becomes a drag, and its trailing click is swallowed. The card can be both,
+ * and `audit:dnd` proves it on every run: a 2px wobble never enters a drag and
+ * still counts as a click.
+ *
+ * THE 2.5.7 CONTROL IS NOT AFFECTED. The menu the card hands out is the
+ * single-pointer, non-dragging route to every move, and it stays exactly where
+ * it was. What the surface removes is the GRIP, which would otherwise be a
+ * second drag source for the same card.
+ *
+ * It also cannot produce a button inside a button: `DragDropSurface` takes a
+ * role only when it owns focus — when it contains no focusable of its own —
+ * and a card carrying the move menu never does.
+ */
+export declare function BoardCardSurface({ className, children }: BoardCardSurfaceProps): import("react").JSX.Element;
+export interface BoardColumnProps<T> {
+    /** `useBoard`'s own computed column — id, label, items, count, wipLimit,
+     *  overWip. Passed straight through; nothing here re-derives it. */
+    column: BoardColumnModel<T>;
+    /**
+     * Rendered in place of `children` when the column has no cards. Content,
+     * not a boolean — supplying THIS is what changes it, matching the
+     * package-wide rule against a `show*`/`with*` switch. Defaults to a
+     * generic message built on `EmptyState` (REUSE: "An empty list, or a
+     * zero-state screen"), sized down for a column rather than a full page.
+     *
+     * HIDDEN, NOT REMOVED, while a drag session is over THIS column. An empty
+     * column's placeholder and the engine's own drop marker (drawn by
+     * `DragDropContainer` itself for a container with nothing else to hang the
+     * marker off — see `DragDrop.tsx`'s `restCount === 0` branch) would
+     * otherwise stack in the same box, and the placeholder's own sentence
+     * ("Drag a card here…") is exactly what the marker is now doing. The
+     * column's accessible name is untouched — `aria-label={column.label}` sits
+     * on the `role="list"` wrapper below, not on this content — so a
+     * screen-reader user still hears which column they are over even while the
+     * placeholder sentence is not rendered. See `BoardColumnBody`.
+     */
+    emptyState?: ReactNode;
+    /**
+     * DX-5637: the number the header badge draws, in place of the column's own
+     * `count`. `count` is the lane's paging length (it feeds the drag engine and the
+     * move menu); a lane whose paging rows are not all the things a person counts
+     * (a container drawn around its children) passes the number to SHOW here. Display
+     * only for paging and the empty state, which still read the model. `null` is a
+     * count not known yet and draws the unknown mark, never the paging count. When
+     * given, the over-limit verdict compares this number to the WIP limit.
+     */
+    headerCount?: number | null;
+    className?: string;
+    /**
+     * Applied to the droppable list, NOT to the column shell that `className`
+     * targets — this is where a column's own scrolling belongs
+     * (`max-h-… overflow-y-auto`, to cap a column shorter than the space it
+     * would otherwise fill).
+     *
+     * It has to be the inner box: put the scroll on the shell and the header
+     * scrolls away with the cards, so a column whose cards have been scrolled
+     * loses the label and count that say what the column IS. The drag engine
+     * already resolves whichever scroller sits under the pointer, so a column
+     * that scrolls here auto-scrolls during a drag with nothing further wired.
+     *
+     * The box already stretches to fill whatever height its own column has
+     * (`flex-1`, below) and already scrolls its overflow (`overflow-y-auto`
+     * baked into `DragDropContainer`'s own recipe for a `y`-axis container) —
+     * this prop is for the rarer case of PINNING a column shorter than that,
+     * not for turning scrolling on in the first place.
+     */
+    listClassName?: string;
+    /**
+     * DX-3981: tints the lane in this colour. Any CSS colour, passed as DATA — a
+     * list's own hex, say; it is mixed into the theme's sunken surface at a
+     * ratio chosen per theme, so the header label and count (ink tokens, never
+     * the accent as text) stay at 4.5:1 or better and a card's border keeps 3:1
+     * against the lane in light and dark (WCAG 1.4.3 / 1.4.11, proven over the
+     * shipped tokens by `lane-contrast.test.ts`). It also re-points the border
+     * token for everything inside the lane to a lane-aware ink mix — the card
+     * boundary is drawn by that border, since a card fill cannot reach 3:1
+     * against a lane that still reads as a tint. The WIP-exceeded header shift
+     * still wins over the tint. Omitted, the lane renders exactly as it always
+     * has.
+     */
+    accent?: string;
+    /**
+     * DX-3981: drawn before the header label, in the label's own ink colour.
+     * Decorative (`aria-hidden`) — the label already names the column, and
+     * never colour or glyph alone (WCAG 1.4.1).
+     */
+    icon?: ReactNode;
+    /**
+     * DX-4540: controls drawn at the header's end, after the count — a
+     * `SortMenu`, say. A slot of content, not a boolean: supplying it is what
+     * adds it. It sits in the header, outside the scrolling list, so it stays
+     * put while the cards scroll.
+     */
+    actions?: ReactNode;
+    /** The column's cards — a `BoardCard` per item, mapped by the consumer
+     *  exactly as `DragDropContainer`'s own children already are. A windowed
+     *  lane puts a `PagedWindowList` here — see the file header. */
+    children?: ReactNode;
+}
+export declare function BoardColumn<T>({ column, emptyState, headerCount, className, listClassName, accent, icon, actions, children, }: BoardColumnProps<T>): import("react").JSX.Element;
+export interface BoardCardProps {
+    id: BoardItemId;
+    /** Position within its OWN column right now — same contract as
+     *  `DragDropItem.index`: the real index in the consumer's data, never a
+     *  filtered render order. */
+    index: number;
+    /** Spoken by the drag engine's announcements and this card's own "Move
+     *  <label>" menu trigger label. Falls back to `id`, which is speakable and
+     *  not great — supply it. */
+    label?: string;
+    className?: string;
+    /**
+     * Card content, 100% consumer-owned — `Board` and `BoardCard` do not know
+     * what is inside. `handle` is the dual-purpose grip-and-menu control (see
+     * the file header); RES-GAME's evidence is that a board renders this
+     * INSIDE its `RecordCardHandle` slot (`RecordCard.tsx` reserves exactly
+     * this region), but nothing here requires that specific composition — it
+     * is a plain `ReactNode`, placeable anywhere the consumer's markup wants a
+     * pointer-operable, non-dragging route to every move this card can make.
+     */
+    children: (handle: ReactNode) => ReactNode;
+}
+export declare function BoardCard({ id, index, label, className, children }: BoardCardProps): import("react").JSX.Element;
+export interface BoardCardGroupProps {
+    /** Unique among this lane's groups and stable across renders: the parent's id, say. A card of the same parent in another lane uses the same id. */
+    id: string;
+    /** Names the set of cards in the box, for assistive technology. */
+    label?: string;
+    /** What sits above the cards inside the box (the parent's title and marks). It moves with the box. */
+    header?: ReactNode;
+    /** Classes for the box's look (a border and fill in the parent's colour): the box is a `RecordCard`, so its corner, border and padding are a lane tile's own. */
+    frameClassName?: string;
+    /** On the group's outer element: its margin and nothing that changes its size while a card is carried. */
+    className?: string;
+    /** The outer element's `data-testid`. */
+    testId?: string;
+    /** On the content inside the box, between the header and the cards (its `gap`). */
+    contentClassName?: string;
+    /** The group's `BoardCard`s, consecutive in the lane. */
+    children: ReactNode;
+    /**
+     * DX-5521: this is one piece of a box the previous piece goes on from (a box whose cards sit on two pages of a windowed lane:
+     * each page draws its own cards in its own piece). The piece has no top edge, no top corners and no padding above its first
+     * card, so it joins the piece above it as one box. Give the `header` to the first piece only. See `DragDropGroup`.
+     */
+    continuesBefore?: boolean;
+    /** DX-5521: the next piece goes on from this one: no bottom edge, corners, padding or margin. See `continuesBefore`. */
+    continuesAfter?: boolean;
+}
+/**
+ * A box drawn around consecutive cards of a lane. The cards stay the lane's own `BoardCard`s, at the lane's own indexes: the box only
+ * changes how a carried card moves through it. The box's frame shrinks when a card is dragged out, grows when one is dragged in, and the
+ * cards and the drop placeholder stay in their own box instead of sliding through its edge (see `DragDropGroup`).
+ */
+export declare function BoardCardGroup({ frameClassName, className, contentClassName, continuesBefore, continuesAfter, ...group }: BoardCardGroupProps): import("react").JSX.Element;