@usefidel/design-system 0.13.0 → 0.15.0

package/dist/index.d.cts

@@ -1,7 +1,11 @@
 import * as react from 'react';
 import { ButtonHTMLAttributes, ReactNode, HTMLAttributes, InputHTMLAttributes } from 'react';
 
-type ButtonVariant = 'primary' | 'outlined' | 'text' | 'neutral' | 'link';
+type ButtonVariant = 'primary' | 'outlined' | 'text' | 'neutral' | 'link'
+/** Final confirm of a destructive action ("Delete my account"). */
+ | 'danger'
+/** Starts a destructive action ("Delete account", "Remove"). */
+ | 'danger-outlined';
 type ButtonSize = 'x-small' | 'small' | 'medium' | 'big';
 interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
     /** Visual style. @default 'primary' */
@@ -248,4 +252,173 @@ interface ToggleProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type'
  */
 declare const Toggle: react.ForwardRefExoticComponent<ToggleProps & react.RefAttributes<HTMLInputElement>>;
 
-export { Button, type ButtonProps, type ButtonSize, type ButtonVariant, type DiffElement, type DiffPropertyLine, DiffPropertyList, type DiffPropertyListProps, DiffSection, type DiffSectionProps, MismatchCard, type MismatchCardProps, type MismatchProperty, Select, type SelectOption, type SelectProps, Toggle, type ToggleProps, type ToggleSize };
+interface AppNavProps extends HTMLAttributes<HTMLElement> {
+    /** Brand mark, usually a link home. */
+    logo: ReactNode;
+    /** Right-hand area (account menu, admin tools). Never shrinks. */
+    actions?: ReactNode;
+    /**
+     * The nav links (`<a>` or a router link). Mark the current page with
+     * `aria-current="page"`; React Router's `NavLink` does this itself.
+     */
+    children?: ReactNode;
+    /** Accessible label for the mobile menu button. @default 'Menu' */
+    menuLabel?: string;
+}
+/**
+ * Fidel design-system app navigation bar. Router-agnostic: it styles whatever
+ * links it is given. Below 640px the links move into a menu opened from a
+ * button at the right of the bar; picking a link, Escape, or a tap outside
+ * closes it.
+ */
+declare function AppNav({ logo, actions, children, menuLabel, className, ...rest }: AppNavProps): react.JSX.Element;
+
+interface TabNavProps extends HTMLAttributes<HTMLElement> {
+    /**
+     * The tab links (`<a>` or a router link). Mark the current tab with
+     * `aria-current="page"`; React Router's `NavLink` does this itself.
+     */
+    children: ReactNode;
+}
+/**
+ * Fidel design-system tab navigation: a row of page-level links with an
+ * underline on the current one. Labels never wrap; when the row is wider than
+ * its container it scrolls sideways. Give it an `aria-label`.
+ */
+declare function TabNav({ children, className, ...rest }: TabNavProps): react.JSX.Element;
+
+interface SettingsSectionProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
+    /** Section heading, rendered as an `h2`. */
+    title: ReactNode;
+    /** Short muted line under the heading. */
+    description?: ReactNode;
+    /** The section's controls and content. */
+    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.
+ */
+declare function SettingsSection({ title, description, children, className, ...rest }: SettingsSectionProps): react.JSX.Element;
+
+type ModalSize = 'small' | 'medium';
+type ModalTone = 'default' | 'danger';
+interface ModalProps {
+    /** Whether the dialog is shown. */
+    open: boolean;
+    /** Called on Escape, the close button, or a click outside the dialog. */
+    onClose: () => void;
+    /** Dialog heading; also its accessible name. */
+    title: ReactNode;
+    /** Muted line under the heading; also its accessible description. */
+    description?: ReactNode;
+    /** Body content. */
+    children?: ReactNode;
+    /** Footer buttons, primary action last. Stacked full width on phones. */
+    actions?: ReactNode;
+    /** Width step: small 420px, medium 560px. @default 'small' */
+    size?: ModalSize;
+    /** False blocks every way of closing, e.g. while an action is in flight. @default true */
+    dismissible?: boolean;
+    /** 'danger' marks a destructive confirm with a warning icon; pair it with a `danger` Button. @default 'default' */
+    tone?: ModalTone;
+    className?: string;
+}
+/**
+ * Fidel design-system Modal. Portalled to `document.body`; traps focus, locks
+ * page scroll, closes on Escape or a click outside, and returns focus to where
+ * it was. Focus starts on the element marked `data-autofocus`, else the first
+ * focusable element.
+ */
+declare function Modal({ open, onClose, title, description, children, actions, size, dismissible, tone, className, }: ModalProps): react.ReactPortal | null;
+
+interface SegmentedOption<T extends string> {
+    value: T;
+    label: ReactNode;
+    /** Optional number shown after the label, e.g. issues in a severity. */
+    count?: number;
+    /** Id of the panel this option shows, for `aria-controls`. */
+    controls?: string;
+    disabled?: boolean;
+}
+interface SegmentedControlProps<T extends string> {
+    options: SegmentedOption<T>[];
+    value: T;
+    onChange: (value: T) => void;
+    /** Names the group for screen readers. */
+    'aria-label': string;
+    className?: string;
+}
+/**
+ * Fidel design-system segmented control: pick one of a few options (a mode,
+ * a filter). Tabs semantics with a roving tabindex: Arrow keys, Home and End
+ * 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;
+
+/**
+ * Layout breakpoints, in px, used as `max-width` media queries.
+ * CSS custom properties can't be read inside `@media`, so component CSS and
+ * consumers write these same numbers literally: `@media (max-width: 640px)`.
+ */
+declare const breakpoints: {
+    /** Phones. */
+    readonly sm: 480;
+    /** Large phones, small tablets. */
+    readonly md: 640;
+    /** Tablets, narrow windows. */
+    readonly lg: 900;
+};
+type Breakpoint = keyof typeof 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;
+
+export { AppNav, type AppNavProps, Avatar, type AvatarProps, type AvatarSize, 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, SectionHeader, type SectionHeaderProps, SegmentedControl, type SegmentedControlProps, type SegmentedOption, Select, type SelectOption, type SelectProps, SettingsSection, type SettingsSectionProps, Split, type SplitProps, TabNav, type TabNavProps, Toggle, type ToggleProps, type ToggleSize, breakpoints };

package/dist/index.d.ts

@@ -1,7 +1,11 @@
 import * as react from 'react';
 import { ButtonHTMLAttributes, ReactNode, HTMLAttributes, InputHTMLAttributes } from 'react';
 
-type ButtonVariant = 'primary' | 'outlined' | 'text' | 'neutral' | 'link';
+type ButtonVariant = 'primary' | 'outlined' | 'text' | 'neutral' | 'link'
+/** Final confirm of a destructive action ("Delete my account"). */
+ | 'danger'
+/** Starts a destructive action ("Delete account", "Remove"). */
+ | 'danger-outlined';
 type ButtonSize = 'x-small' | 'small' | 'medium' | 'big';
 interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
     /** Visual style. @default 'primary' */
@@ -248,4 +252,173 @@ interface ToggleProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type'
  */
 declare const Toggle: react.ForwardRefExoticComponent<ToggleProps & react.RefAttributes<HTMLInputElement>>;
 
-export { Button, type ButtonProps, type ButtonSize, type ButtonVariant, type DiffElement, type DiffPropertyLine, DiffPropertyList, type DiffPropertyListProps, DiffSection, type DiffSectionProps, MismatchCard, type MismatchCardProps, type MismatchProperty, Select, type SelectOption, type SelectProps, Toggle, type ToggleProps, type ToggleSize };
+interface AppNavProps extends HTMLAttributes<HTMLElement> {
+    /** Brand mark, usually a link home. */
+    logo: ReactNode;
+    /** Right-hand area (account menu, admin tools). Never shrinks. */
+    actions?: ReactNode;
+    /**
+     * The nav links (`<a>` or a router link). Mark the current page with
+     * `aria-current="page"`; React Router's `NavLink` does this itself.
+     */
+    children?: ReactNode;
+    /** Accessible label for the mobile menu button. @default 'Menu' */
+    menuLabel?: string;
+}
+/**
+ * Fidel design-system app navigation bar. Router-agnostic: it styles whatever
+ * links it is given. Below 640px the links move into a menu opened from a
+ * button at the right of the bar; picking a link, Escape, or a tap outside
+ * closes it.
+ */
+declare function AppNav({ logo, actions, children, menuLabel, className, ...rest }: AppNavProps): react.JSX.Element;
+
+interface TabNavProps extends HTMLAttributes<HTMLElement> {
+    /**
+     * The tab links (`<a>` or a router link). Mark the current tab with
+     * `aria-current="page"`; React Router's `NavLink` does this itself.
+     */
+    children: ReactNode;
+}
+/**
+ * Fidel design-system tab navigation: a row of page-level links with an
+ * underline on the current one. Labels never wrap; when the row is wider than
+ * its container it scrolls sideways. Give it an `aria-label`.
+ */
+declare function TabNav({ children, className, ...rest }: TabNavProps): react.JSX.Element;
+
+interface SettingsSectionProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
+    /** Section heading, rendered as an `h2`. */
+    title: ReactNode;
+    /** Short muted line under the heading. */
+    description?: ReactNode;
+    /** The section's controls and content. */
+    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.
+ */
+declare function SettingsSection({ title, description, children, className, ...rest }: SettingsSectionProps): react.JSX.Element;
+
+type ModalSize = 'small' | 'medium';
+type ModalTone = 'default' | 'danger';
+interface ModalProps {
+    /** Whether the dialog is shown. */
+    open: boolean;
+    /** Called on Escape, the close button, or a click outside the dialog. */
+    onClose: () => void;
+    /** Dialog heading; also its accessible name. */
+    title: ReactNode;
+    /** Muted line under the heading; also its accessible description. */
+    description?: ReactNode;
+    /** Body content. */
+    children?: ReactNode;
+    /** Footer buttons, primary action last. Stacked full width on phones. */
+    actions?: ReactNode;
+    /** Width step: small 420px, medium 560px. @default 'small' */
+    size?: ModalSize;
+    /** False blocks every way of closing, e.g. while an action is in flight. @default true */
+    dismissible?: boolean;
+    /** 'danger' marks a destructive confirm with a warning icon; pair it with a `danger` Button. @default 'default' */
+    tone?: ModalTone;
+    className?: string;
+}
+/**
+ * Fidel design-system Modal. Portalled to `document.body`; traps focus, locks
+ * page scroll, closes on Escape or a click outside, and returns focus to where
+ * it was. Focus starts on the element marked `data-autofocus`, else the first
+ * focusable element.
+ */
+declare function Modal({ open, onClose, title, description, children, actions, size, dismissible, tone, className, }: ModalProps): react.ReactPortal | null;
+
+interface SegmentedOption<T extends string> {
+    value: T;
+    label: ReactNode;
+    /** Optional number shown after the label, e.g. issues in a severity. */
+    count?: number;
+    /** Id of the panel this option shows, for `aria-controls`. */
+    controls?: string;
+    disabled?: boolean;
+}
+interface SegmentedControlProps<T extends string> {
+    options: SegmentedOption<T>[];
+    value: T;
+    onChange: (value: T) => void;
+    /** Names the group for screen readers. */
+    'aria-label': string;
+    className?: string;
+}
+/**
+ * Fidel design-system segmented control: pick one of a few options (a mode,
+ * a filter). Tabs semantics with a roving tabindex: Arrow keys, Home and End
+ * 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;
+
+/**
+ * Layout breakpoints, in px, used as `max-width` media queries.
+ * CSS custom properties can't be read inside `@media`, so component CSS and
+ * consumers write these same numbers literally: `@media (max-width: 640px)`.
+ */
+declare const breakpoints: {
+    /** Phones. */
+    readonly sm: 480;
+    /** Large phones, small tablets. */
+    readonly md: 640;
+    /** Tablets, narrow windows. */
+    readonly lg: 900;
+};
+type Breakpoint = keyof typeof 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;
+
+export { AppNav, type AppNavProps, Avatar, type AvatarProps, type AvatarSize, 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, SectionHeader, type SectionHeaderProps, SegmentedControl, type SegmentedControlProps, type SegmentedOption, Select, type SelectOption, type SelectProps, SettingsSection, type SettingsSectionProps, Split, type SplitProps, TabNav, type TabNavProps, Toggle, type ToggleProps, type ToggleSize, breakpoints };