@usefidel/design-system 0.17.0 → 0.19.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ButtonHTMLAttributes, ReactNode, AnchorHTMLAttributes, HTMLAttributes, InputHTMLAttributes } from 'react';
+import { ButtonHTMLAttributes, ReactNode, AnchorHTMLAttributes, HTMLAttributes, InputHTMLAttributes, ReactElement } from 'react';
 
 type ButtonVariant = 'primary' | 'outlined' | 'text' | 'neutral' | 'link'
 /** High-contrast near-black, for a page's main create action ("New comparison"). */
@@ -221,8 +221,10 @@ declare function DiffPropertyList({ properties, className, ...rest }: DiffProper
 interface SelectOption {
     value: string;
     label: string;
-    /** Secondary line, e.g. an @handle. */
+    /** Secondary text beside the label, e.g. an @handle. */
     secondary?: string;
+    /** Line under the label explaining the option, e.g. what a role can do. */
+    description?: string;
     /** Leading node (avatar / icon) shown in the option and, when selected, the trigger. */
     avatar?: ReactNode;
     disabled?: boolean;
@@ -246,6 +248,16 @@ interface SelectProps {
     name?: string;
     className?: string;
     containerClassName?: string;
+    /** `field` is the bordered form control; `inline` is a borderless trigger
+     *  that sits inside another control, e.g. an Input's `trailing`. @default 'field' */
+    variant?: 'field' | 'inline';
+    /** `small` is a 32px trigger for table rows and inline use. @default 'medium' */
+    size?: 'medium' | 'small';
+    /** Which edge of the trigger the list lines up with; `end` lets a short
+     *  trigger open a wider list leftwards. @default 'start' */
+    align?: 'start' | 'end';
+    /** Accessible name when there is no visible `label`. */
+    'aria-label'?: string;
 }
 /**
  * Fidel design-system Select — a listbox (optionally searchable) with avatar +
@@ -372,6 +384,10 @@ interface SegmentedControlProps<T extends string> {
     onChange: (value: T) => void;
     /** Names the group for screen readers. */
     'aria-label': string;
+    /** `underline` sits on a baseline like TabNav; `pill` is a grey track with
+     *  the selected option raised, for a two- or three-way switch inside a
+     *  form or above content. @default 'underline' */
+    variant?: 'underline' | 'pill';
     className?: string;
 }
 /**
@@ -380,7 +396,7 @@ interface SegmentedControlProps<T extends string> {
  * move and select; Tab leaves the group. When the options don't fit, the row
  * scrolls sideways instead of widening the page.
  */
-declare function SegmentedControl<T extends string>({ options, value, onChange, 'aria-label': ariaLabel, className, }: SegmentedControlProps<T>): react.JSX.Element;
+declare function SegmentedControl<T extends string>({ options, value, onChange, 'aria-label': ariaLabel, variant, className, }: SegmentedControlProps<T>): react.JSX.Element;
 
 /**
  * Layout breakpoints, in px, used as `max-width` media queries.
@@ -462,6 +478,8 @@ declare function Badge({ tone, icon, className, children, ...rest }: BadgeProps)
 interface TagProps extends HTMLAttributes<HTMLSpanElement> {
     /** Colour of the leading dot. Leave out for no dot. */
     dot?: Tone;
+    /** Leading icon, drawn at 14px, e.g. a repository or branch mark. */
+    icon?: ReactNode;
     children: ReactNode;
 }
 /**
@@ -469,7 +487,7 @@ interface TagProps extends HTMLAttributes<HTMLSpanElement> {
  * optional coloured dot. Measured from Figma "✅Project" comparison-type chip
  * (node 231:59808).
  */
-declare function Tag({ dot, className, children, ...rest }: TagProps): react.JSX.Element;
+declare function Tag({ dot, icon, className, children, ...rest }: TagProps): react.JSX.Element;
 
 interface MultiSelectOption {
     value: string;
@@ -481,8 +499,17 @@ interface MultiSelectOption {
     disabled?: boolean;
 }
 interface MultiSelectProps {
-    /** Trigger text, e.g. "Status". Also the list's accessible name. */
+    /** Trigger text, e.g. "Status", or the field's label in the `field`
+     *  variant. Also the list's accessible name. */
     label: string;
+    /** `filter` is a compact trigger with an "n/m" count; `field` is a
+     *  full-width form field with its label above and the chosen options as
+     *  removable chips. @default 'filter' */
+    variant?: 'filter' | 'field';
+    /** `field` only: text in the box while nothing is chosen. */
+    placeholder?: string;
+    /** Show Select all / Clear under the list. @default true for `filter`, false for `field` */
+    showActions?: boolean;
     options: MultiSelectOption[];
     /** Selected values. An empty list means nothing is ticked. */
     value: string[];
@@ -496,11 +523,12 @@ interface MultiSelectProps {
 /**
  * Fidel design-system MultiSelect: a filter menu of checkbox options, each
  * with an optional dot and count, and Select all / Clear in the footer. The
- * trigger shows "n/m" once anything is ticked. Keyboard: Enter/Space/↓ open;
+ * trigger shows "n/m" once anything is ticked. The `field` variant is a form
+ * field instead: label above, chosen options as chips you can remove. Keyboard: Enter/Space/↓ open;
  * ↑/↓/Home/End move; Enter/Space toggle; Esc closes. Measured from Figma
  * "✅Project" filter Select (node 231:60682).
  */
-declare function MultiSelect({ label, options, value, onChange, disabled, selectAllLabel, clearLabel, id, className, }: MultiSelectProps): react.JSX.Element;
+declare function MultiSelect({ label, variant, placeholder, showActions, options, value, onChange, disabled, selectAllLabel, clearLabel, id, className, }: MultiSelectProps): react.JSX.Element;
 
 interface SearchInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type'> {
     /** Keyboard hint shown at the end while the field is empty, e.g. "/". */
@@ -540,13 +568,16 @@ interface EmptyStateProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'>
     action?: ReactNode;
     /** Secondary line under the action, e.g. a help link. */
     footer?: ReactNode;
+    /** `compact` for an empty list inside a card or table: smaller title and
+     *  spacing, and the illustration (usually an icon) keeps its own size. @default 'default' */
+    size?: 'default' | 'compact';
 }
 /**
  * Fidel design-system EmptyState: a centred illustration, title, description,
  * action and footer, for a list or page with nothing in it yet. Measured from
  * Figma "✅Project" Empty State Container (node 231:59661).
  */
-declare function EmptyState({ illustration, title, description, action, footer, className, ...rest }: EmptyStateProps): react.JSX.Element;
+declare function EmptyState({ illustration, title, description, action, footer, size, className, ...rest }: EmptyStateProps): react.JSX.Element;
 /**
  * Two tilted cards with a search badge: "nothing found yet". Drawn from the
  * Figma "Stacked Cards" layers (node 80:49887), 240×160.
@@ -603,4 +634,229 @@ interface SkeletonGroupProps extends HTMLAttributes<HTMLDivElement> {
 /** Wraps a skeleton layout and announces it once as loading (role="status"). */
 declare function SkeletonGroup({ label, className, children, ...rest }: SkeletonGroupProps): react.JSX.Element;
 
-export { AppNav, type AppNavProps, Avatar, type AvatarProps, type AvatarSize, Badge, type BadgeProps, type Breakpoint, Button, ButtonLink, type ButtonLinkProps, type ButtonProps, type ButtonSize, type ButtonVariant, Callout, type CalloutProps, type CalloutTone, type DiffElement, type DiffPropertyLine, DiffPropertyList, type DiffPropertyListProps, DiffSection, type DiffSectionProps, EmptyState, type EmptyStateProps, MismatchCard, type MismatchCardProps, type MismatchProperty, Modal, type ModalProps, type ModalSize, type ModalTone, MultiSelect, type MultiSelectOption, type MultiSelectProps, Pagination, type PaginationProps, SearchInput, type SearchInputProps, SectionHeader, type SectionHeaderProps, SegmentedControl, type SegmentedControlProps, type SegmentedOption, Select, type SelectOption, type SelectProps, SettingsSection, type SettingsSectionProps, Skeleton, SkeletonGroup, type SkeletonGroupProps, type SkeletonProps, type SkeletonShape, Split, type SplitProps, StackedCardsIllustration, TabNav, type TabNavProps, Tag, type TagProps, Toggle, type ToggleProps, type ToggleSize, type Tone, breakpoints };
+/** Surface colour. `subtle` is the grey panel, `default` white with a border, `plain` white without one. */
+type CardTone = 'subtle' | 'default' | 'plain';
+type CardPadding = 'none' | 'md' | 'lg';
+interface CardProps extends HTMLAttributes<HTMLDivElement> {
+    /** @default 'default' */
+    tone?: CardTone;
+    /** Inner spacing: 24px (`md`) or 40px (`lg`, 24px on phones). @default 'md' */
+    padding?: CardPadding;
+    children?: ReactNode;
+}
+/**
+ * Fidel design-system Card: a rounded surface that groups related content.
+ * It has no layout of its own; put anything inside. Measured from Figma
+ * "Integrations" frames (nodes 231:66631, 231:67267, 231:67335).
+ */
+declare function Card({ tone, padding, className, children, ...rest }: CardProps): react.JSX.Element;
+
+interface StatProps extends HTMLAttributes<HTMLDivElement> {
+    /** What the number counts, e.g. "Tokens found". */
+    label: ReactNode;
+    /** The figure itself. */
+    value: ReactNode;
+    /** Detail under the figure, e.g. a row of Tags. */
+    children?: ReactNode;
+}
+/**
+ * Fidel design-system Stat: a caption, a large figure and optional detail.
+ * Has no surface; wrap it in a Card. Measured from Figma "Design System
+ * connected" (node 231:67335).
+ */
+declare function Stat({ label, value, children, className, ...rest }: StatProps): react.JSX.Element;
+
+interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'size'> {
+    /** Text beside the box. Without one, pass `aria-label`. */
+    label?: ReactNode;
+    /** Secondary line under the label. */
+    description?: ReactNode;
+    /** Shows a dash for "some of these"; screen readers announce it as mixed. */
+    indeterminate?: boolean;
+}
+/**
+ * Fidel design-system Checkbox. Renders a native checkbox, visually hidden
+ * over a drawn box, so checked/indeterminate/disabled/focus come from the
+ * input itself and every standard input attribute passes through. Built like
+ * Toggle; checked is ink-filled to match the Integrations frames.
+ */
+declare const Checkbox: react.ForwardRefExoticComponent<CheckboxProps & react.RefAttributes<HTMLInputElement>>;
+
+interface RadioProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'size'> {
+    /** Text beside the circle. Without one, pass `aria-label`. */
+    label?: ReactNode;
+    /** Secondary line under the label. */
+    description?: ReactNode;
+}
+/**
+ * Fidel design-system Radio: one choice of several. Give every Radio in a
+ * set the same `name`, and wrap the set in a `role="radiogroup"` element (or
+ * a fieldset) with a label. Built like Checkbox: a native input over a drawn
+ * circle, ink-filled when chosen.
+ */
+declare const Radio: react.ForwardRefExoticComponent<RadioProps & react.RefAttributes<HTMLInputElement>>;
+
+interface AccordionProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+    /** Header content, always visible. Clicking it opens and closes the body. */
+    summary: ReactNode;
+    /**
+     * Controls in the header that do their own thing, e.g. a Retry button.
+     * Kept outside the toggle so they stay separate keyboard stops.
+     */
+    actions?: ReactNode;
+    /** Controlled open state. */
+    open?: boolean;
+    /** Initial open state when uncontrolled. @default false */
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Body, shown while open. */
+    children?: ReactNode;
+}
+/**
+ * Fidel design-system Accordion: one row that expands to show more. Stack
+ * several for a list. The header is a button with `aria-expanded`; the
+ * chevron on the right points down when closed and up when open.
+ */
+declare function Accordion({ summary, actions, open: openProp, defaultOpen, onOpenChange, children, className, ...rest }: AccordionProps): react.JSX.Element;
+
+type StepStatus = 'done' | 'active' | 'pending' | 'failed';
+interface Step {
+    id: string;
+    label: ReactNode;
+    status: StepStatus;
+}
+interface StepListProps extends Omit<HTMLAttributes<HTMLOListElement>, 'children'> {
+    steps: Step[];
+}
+/**
+ * Fidel design-system StepList: an ordered list of steps, each done, in
+ * progress, not started or failed. The in-progress step is marked
+ * `aria-current="step"`. Measured from Figma "Scanning" (node 231:67267).
+ */
+declare function StepList({ steps, className, ...rest }: StepListProps): react.JSX.Element;
+
+interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
+    /** Text above the field. Without one, pass `aria-label`. */
+    label?: ReactNode;
+    /** Muted line under the field, e.g. why it is locked. */
+    hint?: ReactNode;
+    /** Replaces the hint and marks the field invalid. */
+    error?: ReactNode;
+    /** Icon before the value, e.g. a lock on a read-only field. */
+    leadingIcon?: ReactNode;
+    /** Control inside the field after the value, e.g. a compact Select. */
+    trailing?: ReactNode;
+    /** Classes for the outer field (label + box + message). */
+    containerClassName?: string;
+}
+/**
+ * Fidel design-system Input: a labelled text field with an optional leading
+ * icon, a trailing control inside the box, and a hint or error underneath.
+ * Read-only and disabled fields render on the grey surface. Every standard
+ * input attribute passes through, so it works with react-hook-form's
+ * `register`. Measured from Figma Settings · General and Team frames.
+ */
+declare const Input: react.ForwardRefExoticComponent<InputProps & react.RefAttributes<HTMLInputElement>>;
+
+type IconButtonVariant = 'outlined' | 'ghost';
+type IconButtonSize = 'small' | 'medium';
+interface IconButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+    /** The icon; drawn at 18px (`medium`) or 16px (`small`). */
+    icon: ReactNode;
+    /** Names the action for screen readers, since there is no visible text. */
+    'aria-label': string;
+    /** @default 'outlined' */
+    variant?: IconButtonVariant;
+    /** 44px (`medium`, matches Button medium) or 28px (`small`). @default 'medium' */
+    size?: IconButtonSize;
+}
+/**
+ * Fidel design-system IconButton: a square button holding only an icon, for
+ * actions like regenerate, edit, delete or "more". Measured from Figma
+ * Settings · Team (regenerate link) and Privacy & Security (row menu).
+ */
+declare function IconButton({ icon, variant, size, type, className, ...rest }: IconButtonProps): react.JSX.Element;
+
+interface MenuItem {
+    label: ReactNode;
+    onSelect: () => void;
+    /** `danger` for destructive actions, e.g. "Sign out of this device". */
+    tone?: 'default' | 'danger';
+    icon?: ReactNode;
+    disabled?: boolean;
+}
+interface MenuProps {
+    /** The button that opens the menu, usually an IconButton. It gets the click and ARIA wiring. */
+    trigger: ReactElement;
+    items: MenuItem[];
+    /** Which edge of the trigger the menu lines up with. @default 'end' */
+    align?: 'start' | 'end';
+    className?: string;
+}
+/**
+ * Fidel design-system Menu: a short list of actions opened from a button,
+ * e.g. a row's "more" menu. Keyboard: Enter/Space/↓ on the trigger open it;
+ * ↑/↓/Home/End move; Enter/Space choose; Esc and Tab close; clicking outside
+ * closes.
+ */
+declare function Menu({ trigger, items, align, className }: MenuProps): react.JSX.Element;
+
+interface TableColumn<Row> {
+    key: string;
+    header: ReactNode;
+    /** Renders this column's cell for a row. */
+    cell: (row: Row) => ReactNode;
+    /** @default 'start' */
+    align?: 'start' | 'end';
+    /** CSS width, e.g. '120px' or '40%'. */
+    width?: string;
+}
+interface TableProps<Row> extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    columns: TableColumn<Row>[];
+    rows: Row[];
+    /** Stable key for each row. */
+    rowKey: (row: Row) => string;
+    /** Shown under the header when `rows` is empty, e.g. an EmptyState. */
+    empty?: ReactNode;
+    /** Names the table for screen readers. */
+    'aria-label': string;
+}
+/**
+ * Fidel design-system Table: a grey header row over hairline-divided rows,
+ * for records people scan by column, like payments. With no rows it keeps
+ * the header and shows `empty` beneath it. Scrolls sideways on narrow
+ * screens instead of squashing columns. Measured from Figma Settings ·
+ * Billing history.
+ */
+declare function Table<Row>({ columns, rows, rowKey, empty, className, 'aria-label': ariaLabel, ...rest }: TableProps<Row>): react.JSX.Element;
+
+interface PricingCardProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
+    /** Small label above the name, e.g. "Current plan". */
+    eyebrow?: ReactNode;
+    /** Plan name, rendered as an `h3`. */
+    title: ReactNode;
+    /** Beside the name, e.g. a "Beta" tag. */
+    badge?: ReactNode;
+    /** Formatted price, e.g. "$29". */
+    price: ReactNode;
+    /** After the price, e.g. "/ month". */
+    period?: ReactNode;
+    description?: ReactNode;
+    /** Usually a full-width Button. */
+    action?: ReactNode;
+    /** Heading over the feature list. @default 'Features' */
+    featuresTitle?: ReactNode;
+    /** Line above the list, e.g. "Everything in Free, plus". */
+    featuresIntro?: ReactNode;
+    features?: ReactNode[];
+    /** Accent outline and tint, for the plan you're recommending. */
+    highlighted?: boolean;
+}
+/**
+ * Fidel design-system PricingCard: one plan's name, price, action and
+ * features. The top sits on a raised panel; the feature list sits below it on
+ * the card's tint. Measured from Figma Settings · Plan (node 384:14395).
+ */
+declare function PricingCard({ eyebrow, title, badge, price, period, description, action, featuresTitle, featuresIntro, features, highlighted, className, ...rest }: PricingCardProps): react.JSX.Element;
+
+export { Accordion, type AccordionProps, AppNav, type AppNavProps, Avatar, type AvatarProps, type AvatarSize, Badge, type BadgeProps, type Breakpoint, Button, ButtonLink, type ButtonLinkProps, type ButtonProps, type ButtonSize, type ButtonVariant, Callout, type CalloutProps, type CalloutTone, Card, type CardPadding, type CardProps, type CardTone, Checkbox, type CheckboxProps, type DiffElement, type DiffPropertyLine, DiffPropertyList, type DiffPropertyListProps, DiffSection, type DiffSectionProps, EmptyState, type EmptyStateProps, IconButton, type IconButtonProps, type IconButtonSize, type IconButtonVariant, Input, type InputProps, Menu, type MenuItem, type MenuProps, MismatchCard, type MismatchCardProps, type MismatchProperty, Modal, type ModalProps, type ModalSize, type ModalTone, MultiSelect, type MultiSelectOption, type MultiSelectProps, Pagination, type PaginationProps, PricingCard, type PricingCardProps, Radio, type RadioProps, SearchInput, type SearchInputProps, SectionHeader, type SectionHeaderProps, SegmentedControl, type SegmentedControlProps, type SegmentedOption, Select, type SelectOption, type SelectProps, SettingsSection, type SettingsSectionProps, Skeleton, SkeletonGroup, type SkeletonGroupProps, type SkeletonProps, type SkeletonShape, Split, type SplitProps, StackedCardsIllustration, Stat, type StatProps, type Step, StepList, type StepListProps, type StepStatus, TabNav, type TabNavProps, Table, type TableColumn, type TableProps, Tag, type TagProps, Toggle, type ToggleProps, type ToggleSize, type Tone, breakpoints };