@50arms/ui 0.0.0-stage → 35.1.0

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

@@ -0,0 +1,30 @@
+import { type ReactNode } from "react";
+export interface EmojiOption {
+    /** What is stored and handed back to `onChange`. */
+    value: string;
+    /** What is drawn for it. */
+    glyph: ReactNode;
+    /** The spoken name. */
+    label: string;
+}
+export interface EmojiPickerProps {
+    /** The current stored value, or `null`/absent for none. */
+    value: string | null | undefined;
+    onChange: (value: string | null) => void;
+    /** Accessible name of the trigger and the grid, e.g. "Emoji for Backlog". */
+    label: string;
+    /** The choices. Default: 24 Unicode emoji whose value is the character. */
+    options?: readonly EmojiOption[];
+    /** Show the field that takes a value not among `options`. @default true */
+    allowCustom?: boolean;
+    /** Whether a typed value is acceptable. @default exactly one Unicode emoji */
+    validateCustom?: (text: string) => boolean;
+    /** Draws a stored value that is not among `options`. @default the value as text */
+    renderValue?: (value: string) => ReactNode;
+    /** Offer a way to remove the emoji (`onChange(null)`). @default true */
+    clearable?: boolean;
+    /** Add a search box that filters `options` by label and value, and draw at most 160 matches at once. @default false */
+    searchable?: boolean;
+    className?: string;
+}
+export declare function EmojiPicker({ value, onChange, label, options, allowCustom, validateCustom, renderValue, clearable, searchable, className, }: EmojiPickerProps): import("react").JSX.Element;

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

@@ -0,0 +1,43 @@
+import { Component, type ErrorInfo, type ReactNode } from "react";
+export interface ErrorBoundaryProps {
+    children: ReactNode;
+    /** Shown in the fallback so the failing region is identifiable at a glance. */
+    label?: string;
+    /**
+     * Changing this clears a previously-caught error (SG-833 slice 7).
+     *
+     * A class component's error state is sticky by design — once caught,
+     * `render()` keeps returning the fallback forever, even once whatever
+     * crashed it is no longer what is being shown. That is correct for a
+     * boundary wrapping a fixed region, and wrong for one wrapping a slot whose
+     * CONTENT changes identity underneath it — a list row that starts showing a
+     * different record after a filter or a re-fetch reorders things, for
+     * instance. Passing something that identifies the current content (a
+     * record id, a list key) un-catches the boundary the moment that identity
+     * changes, rather than leaving it permanently wearing a previous item's
+     * crash.
+     *
+     * Omit it for a boundary around a genuinely fixed region — the default
+     * behaviour (sticky until unmount) is unchanged when this is left out.
+     */
+    resetKey?: unknown;
+    /**
+     * Called once per caught error, with React's own error and component stack
+     * (DX-4075). For a consumer that has to REPORT a render failure — a framed
+     * harness posting it to its host — rather than only show it. The fallback and
+     * the console log are unchanged whether or not this is passed.
+     */
+    onError?: (error: Error, info: ErrorInfo) => void;
+}
+interface State {
+    error: Error | null;
+    resetKey?: unknown;
+}
+export declare class ErrorBoundary extends Component<ErrorBoundaryProps, State> {
+    state: State;
+    static getDerivedStateFromError(error: Error): Partial<State>;
+    static getDerivedStateFromProps(props: ErrorBoundaryProps, state: State): Partial<State> | null;
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    render(): 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> | null | undefined;
+}
+export {};

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

@@ -0,0 +1,37 @@
+import type { ReactNode, Ref } from "react";
+export interface FieldProps {
+    label?: ReactNode;
+    /** Helper text. Rendered under the label, and referenced by the control. */
+    description?: ReactNode;
+    /**
+     * An error message. Presence marks the field invalid — one prop rather than
+     * a separate `invalid` boolean, because a field that is invalid with no
+     * message tells the user nothing, and the two are never legitimately apart.
+     */
+    error?: ReactNode;
+    required?: boolean;
+    disabled?: boolean;
+    /** Identifies the field in a form submission. */
+    name?: string;
+    layout?: "stacked" | "inline";
+    className?: string;
+    children: ReactNode;
+    ref?: Ref<HTMLDivElement>;
+}
+export declare function Field({ label, description, error, required, disabled, name, layout, className, children, ref, }: FieldProps): import("react").JSX.Element;
+export interface FieldSetProps {
+    legend?: ReactNode;
+    description?: ReactNode;
+    className?: string;
+    children: ReactNode;
+    ref?: Ref<HTMLFieldSetElement>;
+}
+/**
+ * Groups related fields under a shared legend.
+ *
+ * A real `<fieldset>` / `<legend>` rather than a heading, because a screen
+ * reader announces the legend with EACH control inside it — which is the whole
+ * point for a group of radios or a set of related toggles, and is not something
+ * a heading can do.
+ */
+export declare function FieldSet({ legend, description, className, children, ref }: FieldSetProps): import("react").JSX.Element;

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

@@ -0,0 +1,22 @@
+import type { ReactNode } from "react";
+export type UploadFile = {
+    id: string;
+    file: File;
+    /** 0–100 while uploading; omit when the caller is not tracking it. */
+    progress?: number;
+    error?: string;
+};
+export interface FileUploadProps {
+    files?: UploadFile[];
+    onFilesAdded?: (files: File[]) => void;
+    onFileRemoved?: (id: string) => void;
+    accept?: string;
+    multiple?: boolean;
+    /** Bytes. Files over this are rejected with a message naming the limit. */
+    maxSize?: number;
+    disabled?: boolean;
+    label?: ReactNode;
+    hint?: ReactNode;
+    className?: string;
+}
+export declare function FileUpload({ files, onFilesAdded, onFileRemoved, accept, multiple, maxSize, disabled, label, hint, className, }: FileUploadProps): import("react").JSX.Element;

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

@@ -0,0 +1,120 @@
+import { type ReactNode } from "react";
+import { type BadgeProps } from "./Badge";
+import type { ButtonProps } from "./Button";
+import { type IconName } from "./Icon";
+export type FilterTone = NonNullable<BadgeProps["tone"]>;
+export interface FilterOption<Value extends string = string> {
+    value: Value;
+    /** The option as a person names it ("New", "Bug"). */
+    label: string;
+    /** DX-5436: secondary text drawn after the label in the popover and matched by the search box; never on the active chip, which stays the label alone. */
+    description?: string;
+    /** A registered icon drawn before the label in the popover and on the active chip. */
+    icon?: IconName;
+    /** The colour of the icon and of the active chip. Absent, neutral. */
+    tone?: FilterTone;
+    /**
+     * DXUI-74: a CSS colour (hex, `rgb()`, `oklch()`, a `var()`) for an option whose colour a person chose and so cannot be one of the fixed `tone`s (a roadmap phase's).
+     * The active chip is a `Badge` in that `color`; the option in the popover leads with a dot of it. Give it instead of `tone`, never both: the option throws.
+     */
+    color?: string;
+}
+interface FilterFieldBase {
+    /** Stable id of the filter. */
+    key: string;
+    /** The filter as a person names it ("Status"). Heads its group and prefixes its chips. */
+    label: string;
+}
+interface OptionFilterBase<Value extends string> extends FilterFieldBase {
+    /** The options on offer. With `loadOptions` these are the ones known before it resolves (often none); once it resolves, its result is what the popover offers. */
+    options: readonly FilterOption<Value>[];
+    /** A search box over a scrolling list of the options, for a long set. */
+    searchable?: boolean;
+    /**
+     * DXUI-40: reads the options the first time the popover opens, once. The result is kept for as long as the menu is mounted;
+     * while it runs the popover says it is loading, and a rejection draws a Try again button that reads it again. The trigger and
+     * the chips never change shape: they draw from `options` and the applied values alone.
+     */
+    loadOptions?: () => Promise<readonly FilterOption<Value>[]>;
+    /** DXUI-40: a `searchable` field draws at most this many matches, with a "First N of M" line above them when more match. Absent, every match. */
+    maxShown?: number;
+    /** DXUI-40: `list` draws one option per line instead of wrapping chips. */
+    layout?: "wrap" | "list";
+    /** DXUI-40: an applied value that no option offers is kept and drawn as a chip by its value, instead of throwing. For a value that comes from a URL and may name something the list no longer has, or that is set before `loadOptions` resolves. */
+    keepUnlisted?: boolean;
+    /**
+     * DXUI-42: on a `searchable` field, typed text (trimmed, not blank) that matches no option exactly adds a `Create "<text>"` row. Choosing it
+     * (click, or Enter in the search box) awaits this with the trimmed text; the option it returns is applied to the field, the search clears,
+     * and a `loadOptions` field lists it without a reload. A rejection shows its message under the search box and applies nothing; the row
+     * cannot be chosen again while it runs. The caller must offer the returned option in `options` once it re-renders (its chip is drawn from
+     * there), or set `keepUnlisted`.
+     */
+    onCreate?: (text: string) => Promise<FilterOption<Value>>;
+    /** DXUI-42: the Create row's label for the typed text; absent, the library's localised string. */
+    createLabel?: (text: string) => string;
+}
+/** One value of a closed set at a time: pressing the active option turns the filter off. */
+export interface FilterSingleField<Value extends string = string> extends OptionFilterBase<Value> {
+    kind: "single";
+    /** The chosen value; `undefined` is "any". */
+    value: Value | undefined;
+    onValueChange(value: Value | undefined): void;
+}
+/** Any number of values of a closed set at once. */
+export interface FilterMultipleField<Value extends string = string> extends OptionFilterBase<Value> {
+    kind: "multiple";
+    value: readonly Value[];
+    onValueChange(value: Value[]): void;
+}
+/** An on/off switch. The filter is active while it is on. */
+export interface FilterBooleanField extends FilterFieldBase {
+    kind: "boolean";
+    value: boolean;
+    onValueChange(value: boolean): void;
+}
+/** A calendar range as ISO dates (`2025-03-11`); either end may be open (`null`). */
+export interface FilterDateRange {
+    from: string | null;
+    to: string | null;
+}
+export interface FilterDateRangeField extends FilterFieldBase {
+    kind: "date-range";
+    value: FilterDateRange;
+    onValueChange(value: FilterDateRange): void;
+}
+/** Free text, reported when the person presses Enter or leaves the box. An empty (or blank) text is "any". */
+export interface FilterTextField extends FilterFieldBase {
+    kind: "text";
+    value: string;
+    placeholder?: string;
+    onValueChange(value: string): void;
+}
+export type FilterField<Value extends string = string> = FilterSingleField<Value> | FilterMultipleField<Value> | FilterBooleanField | FilterDateRangeField | FilterTextField;
+/** A single-value field, typed by its own value set: the value and the callback share `Value`, inferred from the options. */
+export declare function singleFilter<Value extends string>(field: Omit<FilterSingleField<Value>, "kind">): FilterField;
+/** A multi-value field, typed by its own value set. */
+export declare function multipleFilter<Value extends string>(field: Omit<FilterMultipleField<Value>, "kind">): FilterField;
+/** How many filters are on across the fields (each value of a `multiple` field counts; a date range counts once). */
+export declare function activeFilterCount(fields: readonly FilterField[]): number;
+export interface FilterMenuProps {
+    fields: readonly FilterField[];
+    /** Turns every filter off in one step. */
+    onClearAll: () => void;
+    /** Names the control for assistive technology, e.g. "Filter feedback". The number of active filters is appended to it. */
+    "aria-label": string;
+    /** The button's icon: the funnel by default; a list that filters by one kind of thing names it instead (a thread's tags: `tag`). */
+    icon?: IconName;
+    size?: ButtonProps["size"];
+    align?: "start" | "center" | "end";
+    className?: string;
+}
+export declare function FilterMenu({ fields, onClearAll, "aria-label": ariaLabel, icon, size, align, className }: FilterMenuProps): import("react").JSX.Element;
+/** An option toggle that carries a description: at most the group's width, and allowed to shrink so the description's `truncate` applies. */
+export declare const OPTION_WITH_DESCRIPTION = "min-w-0 max-w-full shrink justify-start";
+export interface FilterChipsProps {
+    fields: readonly FilterField[];
+    className?: string;
+}
+/** One removable chip per active filter value. Draws nothing while no filter is on. */
+export declare function FilterChips({ fields, className }: FilterChipsProps): ReactNode;
+export {};

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

@@ -0,0 +1,79 @@
+import type { ReactNode } from "react";
+import { type BadgeProps } from "./Badge";
+import { type IconName } from "./Icon";
+/** One finding a gate's reviewer raised. */
+export interface GatesSectionFinding {
+    title: string;
+    /** Its status word, in the caller's language. */
+    status: string;
+    /** Markdown; blank draws no body. */
+    description: string;
+}
+/** What every gate card has, carried or not. */
+interface GatesSectionGateBase {
+    id: string;
+    /** DXUI-36: a readable label ("Dependency Plan"), drawn in the normal text font, never a code identifier in monospace. */
+    name: string;
+    /** DXUI-34: drawn at the right end of the header row (a host's on/off switch); the name truncates before it moves. */
+    control?: ReactNode;
+}
+/** DXUI-34: a help icon after the name opens a popover with `help` (rich content) on hover, keyboard focus and tap; its accessible name is `helpLabel`, e.g. "About Dependency Review". */
+type GatesSectionGateHelp = {
+    help: ReactNode;
+    helpLabel: string;
+} | {
+    help?: undefined;
+    helpLabel?: undefined;
+};
+/** A gate the card carries: its verdict, message, note and findings are drawn. */
+export type GatesSectionCarriedGate = GatesSectionGateBase & GatesSectionGateHelp & GatesSectionCarriedFields;
+interface GatesSectionCarriedFields {
+    /** DXUI-34: omit, or false, for a carried gate. */
+    inactive?: false;
+    tone: NonNullable<BadgeProps["tone"]>;
+    icon: IconName;
+    /** The verdict word the badge reads. */
+    verdictLabel: string;
+    /** When and by whom it was signed off, e.g. a `RelativeTime` with a prefix; omit while unsigned. */
+    signedOff?: ReactNode;
+    /** The reviewer's verdict, markdown; blank or omitted draws `noVerdictLabel` instead. */
+    message?: string;
+    /** Why this gate holds this card, drawn under the message; omit for none. */
+    note?: ReactNode;
+    /** What this gate's reviewer raised: the collapsible's trigger ("2 findings") and the findings under it. Omit, or give no items, for none. */
+    findings?: {
+        label: string;
+        items: readonly GatesSectionFinding[];
+    };
+}
+/** DXUI-34: a gate the card does not carry (switched off): its header alone, muted, with no badge, verdict line, note or findings. */
+export type GatesSectionInactiveGate = GatesSectionGateBase & GatesSectionGateHelp & {
+    inactive: true;
+};
+export type GatesSectionGate = GatesSectionCarriedGate | GatesSectionInactiveGate;
+export interface GatesSectionPhase {
+    id: string;
+    title: string;
+    description: string;
+    icon: IconName;
+    /** A short readout after the title, e.g. "1/2 passed". */
+    aside: string;
+    gates: readonly GatesSectionGate[];
+}
+export interface GatesSectionProps {
+    phases: readonly GatesSectionPhase[];
+    /** Said under a gate whose reviewer left no message. */
+    noVerdictLabel: string;
+    className?: string;
+}
+/**
+ * A labelled section's small-caps heading: an optional icon, the title, and an optional readout after it ("1/2 passed").
+ * Exported so a host's own section wrapper (danxbot's card-tab `Subsection`) draws the very same heading.
+ */
+export declare function SectionHeading({ title, icon, aside }: {
+    title: string;
+    icon?: ReactNode;
+    aside?: ReactNode;
+}): import("react").JSX.Element;
+export declare function GatesSection({ phases, noVerdictLabel, className }: GatesSectionProps): import("react").JSX.Element;
+export {};

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

@@ -0,0 +1,40 @@
+import type { SVGProps } from "react";
+import { type IconNode } from "../lib/icons";
+import type { CoreIconName } from "../icons/data";
+export type IconSize = "xs" | "sm" | "md" | "lg" | "xl";
+/**
+ * `(string & {})` keeps the core names as autocomplete suggestions while still
+ * accepting anything a consumer registered. Plain `string` would collapse the
+ * union and lose the suggestions entirely.
+ */
+export type IconName = CoreIconName | (string & {});
+export interface IconProps extends Omit<SVGProps<SVGSVGElement>, "name" | "ref"> {
+    /** A registered icon name. Ignored when `node` is given. */
+    name?: IconName;
+    /** Raw geometry, for an icon that is not worth registering. */
+    node?: IconNode;
+    size?: IconSize;
+    /**
+     * An accessible name. Supplying it makes the icon `role="img"`; omitting it
+     * marks the icon decorative and hides it from assistive tech.
+     *
+     * The DEFAULT IS DECORATIVE, and that is the right default: an icon almost
+     * always sits beside a label that already carries the meaning, and announcing
+     * both makes every button read twice. The exception — an icon that IS the
+     * only label — is the case worth typing a prop for.
+     */
+    label?: string;
+    ref?: React.Ref<SVGSVGElement>;
+}
+/**
+ * Renders registered icon geometry.
+ *
+ * Everything is `currentColor` and sized from CSS variables, so an icon inherits
+ * both the colour and the size scale of whatever it sits in — no per-call
+ * colour prop, and no icon left behind when the user changes the size toggle.
+ *
+ * `shrink-0` is not a detail: an icon inside a flex row with a long label will
+ * otherwise be squeezed into an oval, which is the single most common way icons
+ * break in a real layout.
+ */
+export declare function Icon({ name, node, size, label, className, style, ref, ...props }: IconProps): import("react").JSX.Element | null;

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

@@ -0,0 +1,69 @@
+import type { ReactNode, Ref } from "react";
+import { type ButtonProps } from "./Button";
+import { type CountBadgeTone } from "./CountBadge";
+/** Which `Button` variant backs each (variant, tone) pair. */
+declare const VARIANT_FOR: {
+    readonly ghost: {
+        readonly neutral: "ghost";
+        readonly danger: "ghost-danger";
+    };
+    readonly subtle: {
+        readonly neutral: "subtle";
+        readonly danger: "danger-subtle";
+    };
+    readonly outline: {
+        readonly neutral: "outline";
+        readonly danger: "outline-danger";
+    };
+    readonly solid: {
+        readonly neutral: "solid";
+        readonly danger: "danger";
+    };
+};
+export type IconButtonVariant = keyof typeof VARIANT_FOR;
+export type IconButtonTone = "neutral" | "danger";
+/** A count drawn on the glyph's top-right corner: `neutral` is the quiet gray of a count nothing waits on, `danger` the red of one that does. */
+export type IconButtonBadgeTone = CountBadgeTone;
+export interface IconButtonBadge {
+    /** The number drawn; above 99 it reads `99+`. Zero is drawn too: a count of nothing is still a count. */
+    count: number;
+    tone: IconButtonBadgeTone;
+}
+export interface IconButtonProps extends Omit<ButtonProps, "children" | "iconOnly" | "leadingIcon" | "trailingIcon" | "variant" | "aria-label" | "disabled" | "aria-disabled" | "disabledReasonTooltip"> {
+    /** The glyph. Rendered `aria-hidden` — the name comes from `label`. */
+    icon: ReactNode;
+    /**
+     * The accessible name, and the tooltip text. REQUIRED — an icon carries no
+     * text, so there is no other source for it.
+     *
+     * Name the ACTION and its object ("Delete Phase 2"), not the picture
+     * ("Trash"). It is read aloud in a list of controls where nothing else
+     * distinguishes one row's delete from another's.
+     */
+    label: string;
+    /**
+     * A count drawn as a small round badge over the glyph's top-right corner (a comment button's number of comments). The accessible name stays
+     * `label`: put the count in the label, since the badge itself is `aria-hidden`. A count below 0 or not an integer throws.
+     */
+    badge?: IconButtonBadge;
+    /** Visual weight. Defaults to `ghost` — the right resting state in a row. */
+    variant?: IconButtonVariant;
+    /** `danger` makes the hover destructive. Resting state is unchanged. */
+    tone?: IconButtonTone;
+    /**
+     * Unavailable, AND WHY — there is no boolean form. The string is shown in
+     * the tooltip and announced as the control's description, so the refusal is
+     * never silent.
+     */
+    disabledReason?: string;
+    /**
+     * Suppress the tooltip. For the rare control already named in adjacent
+     * visible text, where a tooltip would only repeat it. The `aria-label` is
+     * unaffected — the name is never optional.
+     */
+    hideTooltip?: boolean;
+    tooltipSide?: "top" | "bottom" | "left" | "right";
+    ref?: Ref<HTMLButtonElement>;
+}
+export declare function IconButton({ icon, label, badge, variant, tone, size, disabledReason, hideTooltip, tooltipSide, className, onClick, ...props }: IconButtonProps): import("react").JSX.Element;
+export {};

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

@@ -0,0 +1,28 @@
+import type { HTMLAttributes, Ref } from "react";
+import { type IconName } from "./Icon";
+export type IconStackTone = "neutral" | "accent" | "success" | "warning" | "danger" | "info" | "muted";
+export interface IconStackBadge {
+    icon: IconName;
+    tone?: IconStackTone;
+}
+export interface IconStackItem {
+    icon: IconName;
+    tone?: IconStackTone;
+    /**
+     * The fact is ABSENT: a dashed, quiet outline in place of the filled chip.
+     * `tone` is ignored — an absent mark is always the muted one.
+     */
+    empty?: boolean;
+    /** A smaller mark pinned to this chip's bottom-right corner. */
+    badge?: IconStackBadge;
+}
+export type IconStackSize = "sm" | "md" | "lg";
+export interface IconStackProps extends Omit<HTMLAttributes<HTMLSpanElement>, "children" | "aria-label"> {
+    /** Marks in paint order: the LAST one is on top. At least one. */
+    items: readonly IconStackItem[];
+    /** The whole combination, in words. REQUIRED — the marks carry no text. */
+    label: string;
+    size?: IconStackSize;
+    ref?: Ref<HTMLSpanElement>;
+}
+export declare function IconStack({ items, label, size, className, ref, ...props }: IconStackProps): import("react").JSX.Element;

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

@@ -0,0 +1,38 @@
+import { type ReactNode, type Ref } from "react";
+export type ImageUploadFieldShape = "circle" | "square";
+export type ImageUploadFieldSize = "sm" | "md" | "lg" | "xl";
+export interface ImageUploadFieldProps {
+    /** The current image URL. `undefined`/`null` means nothing is set yet. */
+    value?: string | null;
+    /**
+     * Fired once a pick resolves — either a successful upload (the URL
+     * `onUpload` returned) or a remove (`null`). This is the only way `value`
+     * ever changes; the component holds no persistent state of its own.
+     */
+    onChange?: (url: string | null) => void;
+    /** Uploads the picked file and resolves with its stored URL. Rejecting
+     *  surfaces the rejection's `message` (or the rejection itself, stringified)
+     *  as this field's error. */
+    onUpload: (file: File) => Promise<string>;
+    shape?: ImageUploadFieldShape;
+    size?: ImageUploadFieldSize;
+    /** Hides the remove control even when a value is set — for a slot that must
+     *  always hold *something* (e.g. a required team logo with a seeded
+     *  default). Default `true`. */
+    removable?: boolean;
+    accept?: string;
+    /** Bytes. Forwarded to `FileUpload`'s own limit + rejection message. */
+    maxSize?: number;
+    disabled?: boolean;
+    /** Rendered above the preview. */
+    label?: ReactNode;
+    /** Rendered under the preview, when there is no error to show instead. */
+    description?: ReactNode;
+    /** Accessible name for the replace/pick control — required since the
+     *  control the preview state renders is icon-only. */
+    uploadLabel?: string;
+    removeLabel?: string;
+    className?: string;
+    ref?: Ref<HTMLDivElement>;
+}
+export declare function ImageUploadField({ value, onChange, onUpload, shape, size, removable, accept, maxSize, disabled, label, description, uploadLabel, removeLabel, className, ref, }: ImageUploadFieldProps): import("react").JSX.Element;