@danxbot/ui 3.5.2 → 3.6.0

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

@@ -0,0 +1,64 @@
+import type { ReactNode } from "react";
+import { type CardHeaderProps } from "./Card";
+export type ConnectionHealth = "healthy" | "degraded" | "broken" | "unknown";
+export interface ConnectionCardProps {
+    /**
+     * The service's brand mark. A consumer normally passes a real logo — an
+     * `<img>`, an inline SVG. Omit it and the card falls back to this library's
+     * own `Icon`, so a catalogue is never missing a media slot entirely just
+     * because one integration has no artwork yet.
+     */
+    logo?: ReactNode;
+    /** The service's name. Plain text — it is composed into the action button's
+     *  accessible name (see `actionLabel`), which a JSX tree cannot be. */
+    name: string;
+    /** What this connection is FOR, one line — "Email via Mailchimp
+     *  Transactional", not "Mailchimp integration". */
+    description?: ReactNode;
+    /** The four-state health model. See the file header for why not a boolean. */
+    status: ConnectionHealth;
+    /** A failure reason, a partial-failure explanation, or a last-checked
+     *  timestamp — whatever the status badge does not already say. Rendered
+     *  only when supplied; omitting it drops the line rather than reserving
+     *  empty space for it. */
+    detail?: ReactNode;
+    /**
+     * The primary action's visible label — typically "Connect" for `unknown`,
+     * "Manage" (or "Reconnect", "Fix") otherwise. Omitting it renders no action
+     * at all, for a read-only tile.
+     *
+     * The button's PROMINENCE follows `status`, not this label's wording: an
+     * `unknown` card gets the solid, high-contrast treatment because getting it
+     * connected is the one thing worth doing; every other state gets the
+     * quieter outline treatment, because the card's border and badge are
+     * already carrying the "look here" signal and a second loud button would
+     * just compete with them.
+     */
+    actionLabel?: string;
+    onAction?: () => void;
+    /**
+     * Present (and non-`undefined`) disables the action and explains why.
+     *
+     * This is `IconButton`'s `disabledReason` contract, carried over verbatim:
+     * `aria-disabled` rather than native `disabled`, so the control stays
+     * hoverable and focusable — a `disabled` button drops out of hit-testing
+     * entirely, and a control nobody can point at can never be asked why it
+     * won't fire. The reason is announced two ways at once, neither of them
+     * "only on hover": an always-present `sr-only` node wired through
+     * `aria-describedby` for a screen reader, and a visible `Tooltip` that opens
+     * on focus as well as on pointer hover, for a keyboard user who generates
+     * no hover event at all.
+     */
+    actionDisabledReason?: string;
+    /**
+     * The heading level the name renders as. See `CardHeader.titleAs` — the
+     * reasoning is identical: a card's correct heading level is a property of
+     * where it sits in the page outline, not of the card, so only the caller
+     * of a whole catalogue grid knows it.
+     *
+     * @default "h3"
+     */
+    titleAs?: CardHeaderProps["titleAs"];
+    className?: string;
+}
+export declare function ConnectionCard({ logo, name, description, status, detail, actionLabel, onAction, actionDisabledReason, titleAs, className, }: ConnectionCardProps): import("react").JSX.Element;

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

@@ -57,7 +57,7 @@ export interface InputProps extends Omit<BaseInput.Props, "className" | "render"
     loading?: boolean;
     ref?: Ref<HTMLInputElement>;
 }
-export declare function Input({ className, size, leading, trailing, loading, ref, ...props }: InputProps): import("react").JSX.Element;
+export declare function Input(allProps: InputProps): import("react").JSX.Element;
 declare const textarea: import("tailwind-variants").TVReturnType<{
     size: {
         sm: "rounded-md px-3 py-2 text-xs";

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

@@ -0,0 +1,48 @@
+import type { Ref } from "react";
+import { type FieldProps } from "./Field";
+import { type InputProps } from "./Input";
+export type SecretValue = {
+    kind: "unchanged";
+} | {
+    kind: "set";
+    value: string;
+} | {
+    kind: "cleared";
+};
+export interface SecretFieldProps extends Pick<FieldProps, "label" | "description" | "error" | "required" | "disabled" | "name" | "className">, Pick<InputProps, "size" | "placeholder"> {
+    /** The pending edit. See the module doc comment for why this is not a `string`. */
+    value: SecretValue;
+    onChange: (value: SecretValue) => void;
+    /**
+     * Whether a secret is CURRENTLY stored server-side, independent of `value`
+     * — this is the fact the empty, masked field is standing in for. Drives the
+     * "a secret is stored" announcement, the hint row, and whether the clear
+     * action is offered at all (there is nothing to clear when nothing is set).
+     */
+    configured: boolean;
+    /**
+     * A partial, already-safe rendering of the stored value — e.g. `{ prefix:
+     * "sk-ab", suffix: "9f4c" }` for a key the consuming app's own API already
+     * truncates before it ever reaches the client. This is NOT the secret; it
+     * is a confirmation aid ("is this the key I think it is?") and is shown
+     * only while a stored value exists and has not been typed over or cleared.
+     */
+    hint?: {
+        prefix: string;
+        suffix: string;
+    };
+    /** When the stored value was last written, for the same confirmation purpose as `hint`. */
+    updatedAt?: string | Date;
+    /** Who wrote it, if the caller's system tracks that. */
+    updatedBy?: string;
+    /**
+     * Offers a show/hide toggle for text the operator just TYPED. Default true.
+     * Never offered for the stored value — see the module doc comment — and
+     * never rendered while there is no typed text to reveal.
+     */
+    revealable?: boolean;
+    /** Label on the destructive confirm button. Default "Clear". */
+    clearConfirmLabel?: string;
+    ref?: Ref<HTMLInputElement>;
+}
+export declare function SecretField({ value, onChange, configured, hint, updatedAt, updatedBy, revealable, clearConfirmLabel, label, description, error, required, disabled, name, placeholder, size, className, ref, }: SecretFieldProps): import("react").JSX.Element;

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

@@ -0,0 +1,130 @@
+import { type ReactNode } from "react";
+import { type CardHeaderProps } from "./Card";
+/**
+ * What `SettingRow` hands to a `control` supplied as a render function —
+ * two ARIA id references to place on the control's own focusable element(s).
+ *
+ * WHY A RENDER PROP, NOT AN AUTOMATIC ASSOCIATION LIKE `Field`.
+ *
+ * `Field` (this library's other labelled wrapper) gets the label/description
+ * link for free, but only because every control it has ever wrapped is one of
+ * THIS library's own Base UI–backed primitives — `Checkbox`, `Switch`,
+ * `Input`, `Select`… — and those read Base UI's internal field context
+ * themselves to pick up `aria-describedby`. That mechanism is a private
+ * implementation detail of Base UI (there is no public hook a third-party
+ * control could subscribe to), so it silently does NOTHING for anything that
+ * is not one of those primitives.
+ *
+ * `SettingRow.control` is typed to accept literally anything a settings page
+ * might need in that slot — a bare `<input>`, a third-party widget, a
+ * composite the CONSUMER wrote that has never heard of this library, let
+ * alone Base UI's field internals. Wrapping arbitrary children in the same
+ * context-based `Field` would look correct and associate nothing, which is
+ * the worse failure: it fails silently, exactly the thing this component
+ * exists to prevent for settings prose.
+ *
+ * So the association is made an explicit VALUE instead of an implicit
+ * context read: `SettingRow` generates the ids, and a `control` passed as a
+ * function receives them and is responsible for spreading them onto the
+ * element that actually receives focus (the switch's button, the input
+ * itself, a slider's thumb — for a multi-thumb control, every thumb).
+ *
+ * `control` may also be passed as a plain `ReactNode` — the escape hatch for
+ * a control that already carries its own accessible name and description
+ * through some other channel (for example a `SwitchField`/`Field`-wrapped
+ * control, or a composite region where per-control labelling does not apply)
+ * — in which case NEITHER id is wired anywhere, and getting the control
+ * properly named and described is entirely the caller's responsibility.
+ */
+export interface SettingRowControlRenderProps {
+    /** Always present — `label` is required, so the row always has a name to give. */
+    "aria-labelledby": string;
+    /** `undefined` when this row has no `description` — nothing to describe with. */
+    "aria-describedby": string | undefined;
+}
+export interface SettingRowBaseProps {
+    /** The setting's name. Always rendered as visible text and always given an id. */
+    label: ReactNode;
+    /**
+     * What the setting actually DOES, in one line. Always visible — see the
+     * module doc comment for why this is not a tooltip. Rendered with a
+     * generated id and, when `control` is a render function, offered to it via
+     * `SettingRowControlRenderProps["aria-describedby"]`.
+     */
+    description?: ReactNode;
+    /**
+     * The long-form "why this matters" — collapsed by default, revealed by a
+     * disclosure built on this library's `Collapsible`. Omit entirely when
+     * `description` alone says everything worth saying; not every setting earns
+     * a second paragraph.
+     */
+    details?: ReactNode;
+    /** Accessible name + visible label of the `details` disclosure trigger. */
+    detailsLabel?: ReactNode;
+    /** Renders the `details` disclosure already open — for a setting a caller deep-links to. */
+    detailsDefaultOpen?: boolean;
+    /**
+     * The CONSEQUENCE of changing this setting, stated plainly — "takes effect
+     * on next dispatch", "requires a worker restart" — never the mechanism. See
+     * the module doc comment: this is what stops a setting from silently not
+     * applying yet.
+     */
+    effect?: ReactNode;
+    /**
+     * Right-aligned indicator — a `Badge` showing the setting's current derived
+     * state, most often. Rendered beside the control, not inside it, so it
+     * survives a `readOnly` row where there is no control at all.
+     */
+    status?: ReactNode;
+    className?: string;
+}
+export interface SettingRowEditableProps extends SettingRowBaseProps {
+    readOnly?: undefined;
+    /**
+     * The setting's control. Either a plain node, or a function receiving the
+     * ids to associate — see `SettingRowControlRenderProps`.
+     */
+    control: ReactNode | ((renderProps: SettingRowControlRenderProps) => ReactNode);
+}
+export interface SettingRowReadOnlyProps extends SettingRowBaseProps {
+    /**
+     * Presents this row as READ-ONLY instead of rendering `control` at all —
+     * see the module doc comment for why this is a first-class state rather
+     * than a disabled control. `reason` is required; `value`, when given, is
+     * the setting's current value, shown as plain text beside it.
+     */
+    readOnly: {
+        reason: ReactNode;
+        value?: ReactNode;
+    };
+    control?: undefined;
+}
+export type SettingRowProps = SettingRowEditableProps | SettingRowReadOnlyProps;
+export declare function SettingRow(props: SettingRowProps): import("react").JSX.Element;
+export interface SettingGroupProps {
+    /** The group's name — e.g. "Notifications", "Dispatch limits". */
+    title: ReactNode;
+    /** One line of context for the whole group. */
+    description?: ReactNode;
+    /** @default "h3" — see `CardHeader`'s own doc comment on why this is the caller's call. */
+    titleAs?: CardHeaderProps["titleAs"];
+    /** Where a Save button or a "last changed" line lives. Rendered as a `CardFooter`. */
+    footer?: ReactNode;
+    className?: string;
+    /** `SettingRow` elements, in display order. */
+    children: ReactNode;
+}
+/**
+ * A titled card holding several `SettingRow`s.
+ *
+ * `SettingGroup` simply IS a `Card` — a fixed shape (`CardHeader` for the
+ * title/description, a divided list of rows, an optional `CardFooter`) built
+ * from parts this library already ships, rather than a new container
+ * component that happens to look like one. Nesting, theming, radius
+ * arithmetic and padding all come from `Card` for free, and any future fix to
+ * that component (the nested-radius correction, for one) reaches every
+ * settings page without this file changing at all. The rows themselves supply
+ * only the divider and the per-row padding — everything else about "a card
+ * with a header" was already solved.
+ */
+export declare function SettingGroup({ title, description, titleAs, footer, className, children, }: SettingGroupProps): import("react").JSX.Element;

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

@@ -24,6 +24,21 @@ export interface DataTableProps<TData> {
     refreshing?: boolean;
     /** Skeleton row count while `loading`. */
     loadingRows?: number;
+    /**
+     * Rows per page. **Omit for no pagination** — that is the default and it is
+     * what every existing consumer already gets, unchanged.
+     *
+     * WHY OPT-IN RATHER THAN A DEFAULT PAGE SIZE: paginating a table nobody
+     * asked to paginate hides rows. A short table that suddenly grows a footer
+     * and a "1 of 3" is a worse regression than a long table, because the rows
+     * that vanished were on screen yesterday. So the caller says when the list
+     * is long enough to warrant it.
+     *
+     * The `Pagination` control this renders has existed in this library since
+     * long before `DataTable` did, as a fully independent component that was
+     * never connected to anything. This is that connection.
+     */
+    pageSize?: number;
     emptyState?: ReactNode;
     onRowClick?: (row: TData) => void;
     /** Rendered above the table; receives the table instance for counts/filters. */
@@ -31,7 +46,7 @@ export interface DataTableProps<TData> {
     className?: string;
     getRowId?: (row: TData, index: number) => string;
 }
-export declare function DataTable<TData>({ data, columns, density, selectable, maxHeight, zebra, loading, refreshing, loadingRows, emptyState, onRowClick, toolbar, className, getRowId, }: DataTableProps<TData>): import("react").JSX.Element;
+export declare function DataTable<TData>({ data, columns, density, selectable, maxHeight, zebra, loading, refreshing, loadingRows, pageSize, emptyState, onRowClick, toolbar, className, getRowId, }: DataTableProps<TData>): import("react").JSX.Element;
 export declare function TableEmptyState({ icon, title, description, action, }: {
     icon?: ReactNode;
     title?: string;

package/dist/types/index.d.ts

@@ -21,6 +21,9 @@ export { Skeleton, SkeletonText, LoadingOverlay, type SkeletonProps, type Skelet
 export { ErrorBoundary } from "./components/ErrorBoundary";
 export { Field, FieldSet, type FieldProps, type FieldSetProps } from "./components/Field";
 export { Input, Textarea, type InputProps, type TextareaProps } from "./components/Input";
+export { SecretField, type SecretFieldProps, type SecretValue } from "./components/SecretField";
+export { SettingRow, SettingGroup, type SettingRowProps, type SettingGroupProps, type SettingRowControlRenderProps, } from "./components/SettingRow";
+export { ConnectionCard, type ConnectionCardProps, type ConnectionHealth, } from "./components/ConnectionCard";
 export { Checkbox, Switch, Radio, RadioGroup, CheckboxField, SwitchField, RadioField, RadioCard, type CheckboxProps, type SwitchProps, type RadioProps, type RadioGroupProps, type CheckboxFieldProps, type SwitchFieldProps, type RadioFieldProps, type RadioCardProps, } from "./components/Choice";
 export { Dialog, DialogClose, AlertDialog, type DialogProps, type AlertDialogProps, } from "./components/Dialog";
 export { Popover, PopoverClose, Tooltip, TooltipProvider, type PopoverProps, type TooltipProps, } from "./components/Popover";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danxbot/ui",
-  "version": "3.5.2",
+  "version": "3.6.0",
   "type": "module",
   "description": "Danxbot — a domain-agnostic React design system with motion as a first-class primitive.",
   "license": "MIT",