@usefidel/design-system 0.14.0 → 0.16.0

package/dist/index.d.cts

@@ -2,6 +2,8 @@ import * as react from 'react';
 import { ButtonHTMLAttributes, ReactNode, HTMLAttributes, InputHTMLAttributes } from 'react';
 
 type ButtonVariant = 'primary' | 'outlined' | 'text' | 'neutral' | 'link'
+/** High-contrast near-black, for a page's main create action ("New comparison"). */
+ | 'dark'
 /** Final confirm of a destructive action ("Delete my account"). */
  | 'danger'
 /** Starts a destructive action ("Delete account", "Remove"). */
@@ -296,6 +298,9 @@ interface SettingsSectionProps extends Omit<HTMLAttributes<HTMLElement>, 'title'
     children?: ReactNode;
 }
 /**
+ * @deprecated Compose `Split` and `SectionHeader` instead; this will be removed
+ * once fidel-web has moved off it.
+ *
  * Fidel design-system settings section: heading and description on the left,
  * content on the right, divided from the next section by a hairline. Stacks
  * into one column below 900px.
@@ -373,4 +378,188 @@ declare const breakpoints: {
 };
 type Breakpoint = keyof typeof breakpoints;
 
-export { AppNav, type AppNavProps, type Breakpoint, Button, type ButtonProps, type ButtonSize, type ButtonVariant, type DiffElement, type DiffPropertyLine, DiffPropertyList, type DiffPropertyListProps, DiffSection, type DiffSectionProps, MismatchCard, type MismatchCardProps, type MismatchProperty, Modal, type ModalProps, type ModalSize, type ModalTone, SegmentedControl, type SegmentedControlProps, type SegmentedOption, Select, type SelectOption, type SelectProps, SettingsSection, type SettingsSectionProps, TabNav, type TabNavProps, Toggle, type ToggleProps, type ToggleSize, breakpoints };
+type AvatarSize = 'small' | 'medium' | 'large';
+interface AvatarProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'children'> {
+    /** Person's name or handle; used for the initials and the accessible name. */
+    name: string;
+    /** Photo URL. Falls back to initials when missing or when it fails to load. */
+    src?: string | null;
+    /** small 24px, medium 32px, large 40px. @default 'medium' */
+    size?: AvatarSize;
+}
+/**
+ * Fidel design-system Avatar: a round photo, or initials on an accent tint
+ * when there is no photo. Exposes `name` as its accessible label.
+ */
+declare function Avatar({ name, src, size, className, ...rest }: AvatarProps): react.JSX.Element;
+
+interface SectionHeaderProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+    title: ReactNode;
+    /** Short muted line under the heading. */
+    description?: ReactNode;
+    /** Heading level. @default 'h2' */
+    as?: 'h2' | 'h3' | 'h4';
+    /** Id for the heading, so a surrounding region can use `aria-labelledby`. */
+    titleId?: string;
+}
+/** Fidel design-system section header: a heading with an optional muted description under it. */
+declare function SectionHeader({ title, description, as: Heading, titleId, className, ...rest }: SectionHeaderProps): react.JSX.Element;
+
+interface SplitProps extends HTMLAttributes<HTMLDivElement> {
+    /** The narrow side column, e.g. a SectionHeader. */
+    aside: ReactNode;
+    /** The main column. */
+    children?: ReactNode;
+    /** Width of the side column. @default '280px' */
+    asideWidth?: string;
+    /** Keep the side column in view while the main column scrolls. @default false */
+    sticky?: boolean;
+    /** Breakpoint below which the columns stack, aside first: md 640px, lg 900px. @default 'lg' */
+    collapseBelow?: 'md' | 'lg';
+}
+/**
+ * Fidel design-system two-column layout: a fixed-width side column beside a
+ * flexible main column, stacking into one column below a breakpoint.
+ */
+declare function Split({ aside, children, asideWidth, sticky, collapseBelow, className, style, ...rest }: SplitProps): react.JSX.Element;
+
+/** Semantic colour roles shared by status components (Badge, Tag, MultiSelect dots). */
+type Tone = 'neutral' | 'info' | 'success' | 'warning' | 'danger';
+
+interface BadgeProps extends HTMLAttributes<HTMLSpanElement> {
+    /** Colour role. @default 'neutral' */
+    tone?: Tone;
+    /** Leading icon, drawn at 12px. */
+    icon?: ReactNode;
+    children: ReactNode;
+}
+/**
+ * Fidel design-system Badge: a tinted pill naming a state ("Checking",
+ * "Checked", "Failed to run"). Measured from Figma "✅Project" status-badge
+ * (node 231:59799).
+ */
+declare function Badge({ tone, icon, className, children, ...rest }: BadgeProps): react.JSX.Element;
+
+interface TagProps extends HTMLAttributes<HTMLSpanElement> {
+    /** Colour of the leading dot. Leave out for no dot. */
+    dot?: Tone;
+    children: ReactNode;
+}
+/**
+ * Fidel design-system Tag: a quiet bordered label for a category, with an
+ * optional coloured dot. Measured from Figma "✅Project" comparison-type chip
+ * (node 231:59808).
+ */
+declare function Tag({ dot, className, children, ...rest }: TagProps): react.JSX.Element;
+
+interface MultiSelectOption {
+    value: string;
+    label: string;
+    /** Coloured dot before the label. */
+    dot?: Tone;
+    /** Trailing count, e.g. how many results the option would show. */
+    count?: number;
+    disabled?: boolean;
+}
+interface MultiSelectProps {
+    /** Trigger text, e.g. "Status". Also the list's accessible name. */
+    label: string;
+    options: MultiSelectOption[];
+    /** Selected values. An empty list means nothing is ticked. */
+    value: string[];
+    onChange: (value: string[]) => void;
+    disabled?: boolean;
+    selectAllLabel?: string;
+    clearLabel?: string;
+    id?: string;
+    className?: string;
+}
+/**
+ * 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;
+ * ↑/↓/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;
+
+interface SearchInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type'> {
+    /** Keyboard hint shown at the end while the field is empty, e.g. "/". */
+    shortcut?: string;
+    /** Class for the wrapper; `className` goes on the input. */
+    containerClassName?: string;
+}
+/**
+ * Fidel design-system SearchInput: a 44px search field with a leading
+ * magnifier. Measured from Figma "✅Project" toolbar search (node 231:59687).
+ */
+declare const SearchInput: react.ForwardRefExoticComponent<SearchInputProps & react.RefAttributes<HTMLInputElement>>;
+
+interface PaginationProps {
+    /** Current page, 1-based. */
+    page: number;
+    pageCount: number;
+    onPageChange: (page: number) => void;
+    /** With `pageSize`, adds "Showing 1–20 of 45" (full variant only). */
+    total?: number;
+    pageSize?: number;
+    /** full: range text + page numbers. compact: "Page 2 of 3" between arrows. @default 'full' */
+    variant?: 'full' | 'compact';
+    className?: string;
+}
+/**
+ * Fidel design-system Pagination. Renders nothing when there is one page.
+ */
+declare function Pagination({ page, pageCount, onPageChange, total, pageSize, variant, className }: PaginationProps): react.JSX.Element | null;
+
+interface EmptyStateProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+    /** Picture above the title, e.g. <StackedCardsIllustration />. */
+    illustration?: ReactNode;
+    title: ReactNode;
+    description?: ReactNode;
+    /** Primary action, usually a Button. */
+    action?: ReactNode;
+    /** Secondary line under the action, e.g. a help link. */
+    footer?: ReactNode;
+}
+/**
+ * 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;
+/**
+ * Two tilted cards with a search badge: "nothing found yet". Drawn from the
+ * Figma "Stacked Cards" layers (node 80:49887), 240×160.
+ */
+declare function StackedCardsIllustration({ className }: {
+    className?: string;
+}): react.JSX.Element;
+
+type SkeletonShape = 'rect' | 'text' | 'circle';
+interface SkeletonProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'children'> {
+    /** rect: a block. text: line(s) at text height. circle: an avatar or icon. @default 'rect' */
+    shape?: SkeletonShape;
+    /** CSS width; a number is px. Text defaults to 100%, circle to its height. */
+    width?: number | string;
+    /** CSS height; a number is px. Text defaults to one line (1em). @default 16 for rect and circle */
+    height?: number | string;
+    /** Text only: how many lines. The last of several is shorter, as text usually is. @default 1 */
+    lines?: number;
+}
+/**
+ * Fidel design-system Skeleton: a placeholder shape that pulses while content
+ * loads. Pages compose these into the shape of what's coming (rows, cards,
+ * headers). Purely visual and hidden from assistive tech; wrap a layout in
+ * SkeletonGroup so it's announced once as loading.
+ */
+declare function Skeleton({ shape, width, height, lines, className, style, ...rest }: SkeletonProps): react.JSX.Element;
+interface SkeletonGroupProps extends HTMLAttributes<HTMLDivElement> {
+    /** What's loading, for screen readers. @default 'Loading' */
+    label?: string;
+    children: ReactNode;
+}
+/** 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, type ButtonProps, type ButtonSize, type ButtonVariant, 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 };

package/dist/index.d.ts

@@ -2,6 +2,8 @@ import * as react from 'react';
 import { ButtonHTMLAttributes, ReactNode, HTMLAttributes, InputHTMLAttributes } from 'react';
 
 type ButtonVariant = 'primary' | 'outlined' | 'text' | 'neutral' | 'link'
+/** High-contrast near-black, for a page's main create action ("New comparison"). */
+ | 'dark'
 /** Final confirm of a destructive action ("Delete my account"). */
  | 'danger'
 /** Starts a destructive action ("Delete account", "Remove"). */
@@ -296,6 +298,9 @@ interface SettingsSectionProps extends Omit<HTMLAttributes<HTMLElement>, 'title'
     children?: ReactNode;
 }
 /**
+ * @deprecated Compose `Split` and `SectionHeader` instead; this will be removed
+ * once fidel-web has moved off it.
+ *
  * Fidel design-system settings section: heading and description on the left,
  * content on the right, divided from the next section by a hairline. Stacks
  * into one column below 900px.
@@ -373,4 +378,188 @@ declare const breakpoints: {
 };
 type Breakpoint = keyof typeof breakpoints;
 
-export { AppNav, type AppNavProps, type Breakpoint, Button, type ButtonProps, type ButtonSize, type ButtonVariant, type DiffElement, type DiffPropertyLine, DiffPropertyList, type DiffPropertyListProps, DiffSection, type DiffSectionProps, MismatchCard, type MismatchCardProps, type MismatchProperty, Modal, type ModalProps, type ModalSize, type ModalTone, SegmentedControl, type SegmentedControlProps, type SegmentedOption, Select, type SelectOption, type SelectProps, SettingsSection, type SettingsSectionProps, TabNav, type TabNavProps, Toggle, type ToggleProps, type ToggleSize, breakpoints };
+type AvatarSize = 'small' | 'medium' | 'large';
+interface AvatarProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'children'> {
+    /** Person's name or handle; used for the initials and the accessible name. */
+    name: string;
+    /** Photo URL. Falls back to initials when missing or when it fails to load. */
+    src?: string | null;
+    /** small 24px, medium 32px, large 40px. @default 'medium' */
+    size?: AvatarSize;
+}
+/**
+ * Fidel design-system Avatar: a round photo, or initials on an accent tint
+ * when there is no photo. Exposes `name` as its accessible label.
+ */
+declare function Avatar({ name, src, size, className, ...rest }: AvatarProps): react.JSX.Element;
+
+interface SectionHeaderProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+    title: ReactNode;
+    /** Short muted line under the heading. */
+    description?: ReactNode;
+    /** Heading level. @default 'h2' */
+    as?: 'h2' | 'h3' | 'h4';
+    /** Id for the heading, so a surrounding region can use `aria-labelledby`. */
+    titleId?: string;
+}
+/** Fidel design-system section header: a heading with an optional muted description under it. */
+declare function SectionHeader({ title, description, as: Heading, titleId, className, ...rest }: SectionHeaderProps): react.JSX.Element;
+
+interface SplitProps extends HTMLAttributes<HTMLDivElement> {
+    /** The narrow side column, e.g. a SectionHeader. */
+    aside: ReactNode;
+    /** The main column. */
+    children?: ReactNode;
+    /** Width of the side column. @default '280px' */
+    asideWidth?: string;
+    /** Keep the side column in view while the main column scrolls. @default false */
+    sticky?: boolean;
+    /** Breakpoint below which the columns stack, aside first: md 640px, lg 900px. @default 'lg' */
+    collapseBelow?: 'md' | 'lg';
+}
+/**
+ * Fidel design-system two-column layout: a fixed-width side column beside a
+ * flexible main column, stacking into one column below a breakpoint.
+ */
+declare function Split({ aside, children, asideWidth, sticky, collapseBelow, className, style, ...rest }: SplitProps): react.JSX.Element;
+
+/** Semantic colour roles shared by status components (Badge, Tag, MultiSelect dots). */
+type Tone = 'neutral' | 'info' | 'success' | 'warning' | 'danger';
+
+interface BadgeProps extends HTMLAttributes<HTMLSpanElement> {
+    /** Colour role. @default 'neutral' */
+    tone?: Tone;
+    /** Leading icon, drawn at 12px. */
+    icon?: ReactNode;
+    children: ReactNode;
+}
+/**
+ * Fidel design-system Badge: a tinted pill naming a state ("Checking",
+ * "Checked", "Failed to run"). Measured from Figma "✅Project" status-badge
+ * (node 231:59799).
+ */
+declare function Badge({ tone, icon, className, children, ...rest }: BadgeProps): react.JSX.Element;
+
+interface TagProps extends HTMLAttributes<HTMLSpanElement> {
+    /** Colour of the leading dot. Leave out for no dot. */
+    dot?: Tone;
+    children: ReactNode;
+}
+/**
+ * Fidel design-system Tag: a quiet bordered label for a category, with an
+ * optional coloured dot. Measured from Figma "✅Project" comparison-type chip
+ * (node 231:59808).
+ */
+declare function Tag({ dot, className, children, ...rest }: TagProps): react.JSX.Element;
+
+interface MultiSelectOption {
+    value: string;
+    label: string;
+    /** Coloured dot before the label. */
+    dot?: Tone;
+    /** Trailing count, e.g. how many results the option would show. */
+    count?: number;
+    disabled?: boolean;
+}
+interface MultiSelectProps {
+    /** Trigger text, e.g. "Status". Also the list's accessible name. */
+    label: string;
+    options: MultiSelectOption[];
+    /** Selected values. An empty list means nothing is ticked. */
+    value: string[];
+    onChange: (value: string[]) => void;
+    disabled?: boolean;
+    selectAllLabel?: string;
+    clearLabel?: string;
+    id?: string;
+    className?: string;
+}
+/**
+ * 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;
+ * ↑/↓/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;
+
+interface SearchInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type'> {
+    /** Keyboard hint shown at the end while the field is empty, e.g. "/". */
+    shortcut?: string;
+    /** Class for the wrapper; `className` goes on the input. */
+    containerClassName?: string;
+}
+/**
+ * Fidel design-system SearchInput: a 44px search field with a leading
+ * magnifier. Measured from Figma "✅Project" toolbar search (node 231:59687).
+ */
+declare const SearchInput: react.ForwardRefExoticComponent<SearchInputProps & react.RefAttributes<HTMLInputElement>>;
+
+interface PaginationProps {
+    /** Current page, 1-based. */
+    page: number;
+    pageCount: number;
+    onPageChange: (page: number) => void;
+    /** With `pageSize`, adds "Showing 1–20 of 45" (full variant only). */
+    total?: number;
+    pageSize?: number;
+    /** full: range text + page numbers. compact: "Page 2 of 3" between arrows. @default 'full' */
+    variant?: 'full' | 'compact';
+    className?: string;
+}
+/**
+ * Fidel design-system Pagination. Renders nothing when there is one page.
+ */
+declare function Pagination({ page, pageCount, onPageChange, total, pageSize, variant, className }: PaginationProps): react.JSX.Element | null;
+
+interface EmptyStateProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+    /** Picture above the title, e.g. <StackedCardsIllustration />. */
+    illustration?: ReactNode;
+    title: ReactNode;
+    description?: ReactNode;
+    /** Primary action, usually a Button. */
+    action?: ReactNode;
+    /** Secondary line under the action, e.g. a help link. */
+    footer?: ReactNode;
+}
+/**
+ * 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;
+/**
+ * Two tilted cards with a search badge: "nothing found yet". Drawn from the
+ * Figma "Stacked Cards" layers (node 80:49887), 240×160.
+ */
+declare function StackedCardsIllustration({ className }: {
+    className?: string;
+}): react.JSX.Element;
+
+type SkeletonShape = 'rect' | 'text' | 'circle';
+interface SkeletonProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'children'> {
+    /** rect: a block. text: line(s) at text height. circle: an avatar or icon. @default 'rect' */
+    shape?: SkeletonShape;
+    /** CSS width; a number is px. Text defaults to 100%, circle to its height. */
+    width?: number | string;
+    /** CSS height; a number is px. Text defaults to one line (1em). @default 16 for rect and circle */
+    height?: number | string;
+    /** Text only: how many lines. The last of several is shorter, as text usually is. @default 1 */
+    lines?: number;
+}
+/**
+ * Fidel design-system Skeleton: a placeholder shape that pulses while content
+ * loads. Pages compose these into the shape of what's coming (rows, cards,
+ * headers). Purely visual and hidden from assistive tech; wrap a layout in
+ * SkeletonGroup so it's announced once as loading.
+ */
+declare function Skeleton({ shape, width, height, lines, className, style, ...rest }: SkeletonProps): react.JSX.Element;
+interface SkeletonGroupProps extends HTMLAttributes<HTMLDivElement> {
+    /** What's loading, for screen readers. @default 'Loading' */
+    label?: string;
+    children: ReactNode;
+}
+/** 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, type ButtonProps, type ButtonSize, type ButtonVariant, 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 };