@galaxy-io/dls 1.6.1 → 2.0.0

package/dist/widget/Widget.d.ts

@@ -1,57 +1,173 @@
-import type { PropsWithChildren } from "react";
-/** Surface treatment — how much the card separates from the page behind it. */
+import { type Icon as PhosphorIcon } from "@phosphor-icons/react";
+import { type AriaAttributes, type CSSProperties, type MouseEvent, type ReactNode } from "react";
+/** Card fill (Constitution V-A surface set). */
 export declare enum WidgetVariant {
+    /** `background.base`. */
     BASE = "BASE",
+    /** `background.primary`. The default (1.x default). */
     PRIMARY = "PRIMARY",
-    PRIMARY_ALT = "PRIMARY_ALT",
+    /** `background.secondary`. */
     SECONDARY = "SECONDARY",
-    SECONDARY_ALT = "SECONDARY_ALT",
-    TERTIARY = "TERTIARY",
-    TERTIARY_ALT = "TERTIARY_ALT",
-    SUCCESS = "SUCCESS",
-    ERROR = "ERROR",
-    WARNING = "WARNING",
-    DISABLED = "DISABLED",
-    BLUE = "BLUE",
-    LIME = "LIME",
-    TEAL = "TEAL",
-    YELLOW = "YELLOW",
-    ORANGE = "ORANGE",
-    PURPLE = "PURPLE",
-    PINK = "PINK"
+    /** `background.tertiary`. */
+    TERTIARY = "TERTIARY"
 }
-export interface WidgetProps {
-    /** Not implemented — the component ignores it. Render your own header child. */
-    header?: string;
-    /** A number is px. */
-    minWidth?: number | string;
-    maxWidth?: number | string;
-    minHeight?: number | string;
-    maxHeight?: number | string;
-    /** `width: 100%`. */
-    fillWidth?: boolean;
-    /** `height: 100%`. */
-    fillHeight?: boolean;
-    /** Overrides the default 12px inset. */
-    padding?: React.CSSProperties["padding"];
-    /** Collapse padding to 0. Ignored when `padding` is set. */
-    noPadding?: boolean;
-    /** Suppress the hover treatment even when `onClick` is set. */
-    noHover?: boolean;
-    /** Drop the hairline border. */
-    noBorder?: boolean;
-    /** Not implemented — the component ignores it. */
-    isGradient?: boolean;
-    /** Selected styling — border picks up the Galaxy blue. */
-    isSelected?: boolean;
-    /** @default WidgetVariant.PRIMARY */
-    variant?: WidgetVariant;
-    /** Also flips the cursor to `pointer` and enables the hover treatment. */
-    onClick?: (e: React.MouseEvent<HTMLDivElement>) => void;
+/** Header, footer and body density; canonical rungs `SMALL MEDIUM LARGE` (the 1.x Accordion members). */
+export declare enum WidgetSize {
+    /** 32px header and footer rows, 8px body inset and gap, `body_sm` title, `caption` subheader, 13px icon. */
+    SMALL = "SMALL",
+    /** 40px header and footer rows, 12px body inset and gap, `body_md` title, `body_sm` subheader, 15px icon. The default. */
+    MEDIUM = "MEDIUM",
+    /** 48px header and footer rows, 16px body inset and gap, `body_lg` title, `body_md` subheader, 15px icon. */
+    LARGE = "LARGE"
+}
+/**
+ * What `WidgetGroup` shares with its collapsible Widgets: the open ids and the hooks they call.
+ * @internal
+ */
+export interface WidgetGroupContextValue {
+    /** The effective open Widget ids. */
+    openIds: string[];
+    /** Opens or closes the Widget with `id`; the group applies its single / multiple rule. */
+    setItemOpen: (id: string, isOpen: boolean) => void;
+    /** Registers a Widget's header button for arrow-key movement; `null` unregisters it. */
+    registerToggle: (element: HTMLButtonElement | null, id: string) => void;
 }
 /**
- * The card primitive — a bordered, padded surface that groups related content.
- * Hairline border, no shadow. Compose the inside with `FlexWrapper`.
+ * Plumbing between `WidgetGroup` and its collapsible `Widget`s. `null` outside a group and inside a
+ * Widget's body, so nested Widgets are standalone.
+ * @internal
  */
-declare const Widget: ({ children, minHeight, maxHeight, minWidth, maxWidth, fillWidth, fillHeight, padding, noPadding, noHover, noBorder, isSelected, variant, onClick, }: PropsWithChildren<WidgetProps>) => import("react").JSX.Element;
+export declare const WidgetGroupContext: import("react").Context<WidgetGroupContextValue | null>;
+/** Every Widget prop except the two coupled pairs (`isInteractive` / `onClick`, `isCollapsible` / `header`). */
+interface WidgetBaseProps extends AriaAttributes {
+    /** The body: a column with the size's inset (none with `isFlush`) and gap. */
+    children?: ReactNode;
+    /**
+     * Surface fill of the card.
+     * @default WidgetVariant.PRIMARY
+     */
+    variant?: WidgetVariant;
+    /**
+     * Header, footer and body density: row height, insets, title and subheader step, icon size.
+     * @default WidgetSize.MEDIUM
+     */
+    size?: WidgetSize;
+    /**
+     * The header row's title. A string renders as a medium `Text` at the size's step; a node renders
+     * as-is and must not contain controls (put them in `actions`). Omit it for a body-only card.
+     * Required with `isCollapsible`.
+     */
+    header?: ReactNode;
+    /** A secondary line under the title. Needs `header`. */
+    subheader?: string;
+    /** A leading icon before the title. Pass the component, not an element. Needs `header`. */
+    icon?: PhosphorIcon;
+    /**
+     * Content at the end of the header row: `Button`s at `ButtonSize.SMALL`, a count `Chip` or a
+     * labeled `Beacon`. Pressing it never toggles or activates the card.
+     */
+    actions?: ReactNode;
+    /** A row under the body, separated by a hairline: meta text or a "View all" link. */
+    footer?: ReactNode;
+    /**
+     * Removes the body inset so a table, chart or divided list runs to the card edges.
+     * @default false
+     */
+    isFlush?: boolean;
+    /**
+     * Shows the turning caret at the end of a collapsible header. Only with `isCollapsible`.
+     * @default true
+     */
+    hasCaret?: boolean;
+    /**
+     * Controlled open state of a collapsible card. Pass it with `onOpenChange`. Ignored inside a
+     * `WidgetGroup`, which owns the state.
+     */
+    isOpen?: boolean;
+    /**
+     * Initial open state of a collapsible card while uncontrolled. Ignored inside a `WidgetGroup`
+     * (use its `defaultValue`).
+     * @default false
+     */
+    defaultIsOpen?: boolean;
+    /** Called with the next state when the header of a collapsible card is pressed (also inside a `WidgetGroup`). */
+    onOpenChange?: (isOpen: boolean) => void;
+    /**
+     * The collapsible header (or the interactive card) cannot be pressed and is skipped by Tab; the
+     * title dims. A collapsible body keeps its current state.
+     * @default false
+     */
+    isDisabled?: boolean;
+    /**
+     * Replaces the body with a centered `Spinner`; the header, actions and footer stay.
+     * @default false
+     */
+    isLoading?: boolean;
+    /** Chosen state: a `text.primary` hairline. On an interactive card it is announced as pressed. */
+    isSelected?: boolean;
+    /**
+     * Accessible name of an interactive card. Defaults to the header's text, or the body's text
+     * when there is no header.
+     */
+    ariaLabel?: string;
+    /**
+     * DOM id of the root (a `useId()` value by default). Inside a `WidgetGroup` it is also the value
+     * the group's `value` lists, so pass a stable one when the group is controlled.
+     */
+    id?: string;
+    /** Any `data-*` attribute, forwarded to the root `<div>`. */
+    [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
+    /** Extra class on the root `<div>`. */
+    className?: string;
+    /** Inline style on the root `<div>`; only for setting CSS custom properties. */
+    style?: CSSProperties;
+}
+/** An interactive card (one button, `onClick` required) or a static one (no `onClick`). */
+type WidgetInteractivity = {
+    /**
+     * Makes the whole card one button: hover border, pointer, focus ring, Enter / Space.
+     * Requires `onClick`. Controls belong in `actions`; controls in the body are not
+     * pointer-reachable.
+     * @default false
+     */
+    isInteractive: true;
+    /** Called when an interactive card is activated. Only with `isInteractive`. */
+    onClick: (event: MouseEvent<HTMLButtonElement>) => void;
+} | {
+    /**
+     * Makes the whole card one button: hover border, pointer, focus ring, Enter / Space.
+     * Requires `onClick`. Controls belong in `actions`; controls in the body are not
+     * pointer-reachable.
+     * @default false
+     */
+    isInteractive?: false;
+    /** Called when an interactive card is activated. Only with `isInteractive`. */
+    onClick?: undefined;
+};
+/** A collapsible card (needs a `header` to press) or a fixed one. */
+type WidgetCollapsibility = {
+    /**
+     * Makes the header a disclosure button: pressing it folds the body and footer away (with a
+     * caret unless `hasCaret={false}`). Requires `header`.
+     * @default false
+     */
+    isCollapsible: true;
+    /**
+     * The header row's title. A string renders as a medium `Text` at the size's step; a node
+     * renders as-is and must not contain controls (put them in `actions`). Required with
+     * `isCollapsible`.
+     */
+    header: ReactNode;
+} | {
+    /**
+     * Makes the header a disclosure button: pressing it folds the body and footer away (with a
+     * caret unless `hasCaret={false}`). Requires `header`.
+     * @default false
+     */
+    isCollapsible?: false;
+};
+/** Widget props: a base plus the interactivity and collapsibility unions. */
+export type WidgetProps = WidgetBaseProps & WidgetInteractivity & WidgetCollapsibility;
+/** A card: a bordered surface with an optional (collapsible) header, actions, footer and states. */
+declare const Widget: import("react").ForwardRefExoticComponent<WidgetProps & import("react").RefAttributes<HTMLDivElement>>;
 export default Widget;