@carbonplan/components 13.2.2 → 13.3.0

package/dst/index.d.ts

@@ -0,0 +1,503 @@
+import React, { PropsWithChildren, ReactNode } from 'react';
+import * as theme_ui from 'theme-ui';
+import { BoxProps, GridProps, ResponsiveStyleValue, ThemeUIStyleObject, FlexProps, ThemeUICSSObject, IconButtonProps, Input, LinkProps as LinkProps$1, Slider } from 'theme-ui';
+
+interface AvatarProps extends BoxProps {
+    color?: string;
+    width?: string;
+    maxWidth?: string | number;
+    name?: string;
+    github?: string;
+    alt?: string;
+    src?: string;
+}
+declare const Avatar: ({ color, width, maxWidth, name, github, alt, src, sx, ...props }: AvatarProps) => React.JSX.Element;
+
+type RowProps = GridProps;
+declare const Row: ({ children, sx, columns, gap, ...props }: GridProps) => React.JSX.Element;
+
+declare const sizes$1: {
+    xs: number[];
+    sm: number[];
+    md: number[];
+    lg: number[];
+    xl: number[];
+};
+type SizeKey$1 = keyof typeof sizes$1;
+type Direction = 'horizontal' | 'vertical';
+type SpacingValue = SizeKey$1 | ResponsiveStyleValue<number | string>;
+interface GroupProps {
+    children?: React.ReactNode;
+    direction?: Direction;
+    spacing?: SpacingValue;
+    sx?: ThemeUIStyleObject;
+}
+declare const Group: ({ children, direction, spacing, sx, }: GroupProps) => React.JSX.Element;
+
+declare const sizes: {
+    xs: number[];
+    sm: number[];
+    md: number[];
+    lg: number[];
+    xl: number[];
+};
+type SizeKey = keyof typeof sizes;
+type Alignment = 'left' | 'right';
+interface AvatarGroupProps extends RowProps, GroupProps {
+    members: AvatarProps[];
+    direction?: 'horizontal' | 'vertical';
+    align?: Alignment | Alignment[];
+    spacing?: SizeKey | GridProps['gap'];
+    limit?: number;
+    width?: string;
+    maxWidth?: string | number;
+    fixedCount?: number;
+}
+declare const AvatarGroup: ({ members, direction, align, spacing, limit, width, maxWidth, fixedCount, sx, ...props }: AvatarGroupProps) => React.JSX.Element;
+
+type BadgeProps = BoxProps;
+declare const Badge: ({ sx, children, ...props }: BadgeProps) => React.JSX.Element;
+
+type BlockquoteProps = PropsWithChildren<{}>;
+declare const Blockquote: ({ children }: BlockquoteProps) => React.JSX.Element;
+
+interface ButtonProps extends Omit<BoxProps, 'prefix'>, Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, keyof BoxProps | 'prefix'> {
+    size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    align?: 'baseline' | 'sub' | 'super' | 'text-top' | 'text-bottom' | 'middle' | 'top' | 'bottom' | 'initial';
+    suffix?: (React.ReactElement & {
+        props?: {
+            sx?: ThemeUIStyleObject;
+        };
+    }) | null;
+    prefix?: (React.ReactElement & {
+        props?: {
+            sx?: ThemeUIStyleObject;
+        };
+    }) | null;
+    inverted?: boolean;
+    href?: string;
+    internal?: boolean;
+}
+declare const _default$5: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLAnchorElement | HTMLButtonElement>>;
+
+interface CalloutProps extends React.AnchorHTMLAttributes<HTMLElement>, Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, keyof React.AnchorHTMLAttributes<HTMLElement>> {
+    label: ReactNode;
+    children: ReactNode;
+    inverted?: boolean;
+    internal?: boolean;
+    sx?: ThemeUIStyleObject;
+}
+declare const _default$4: React.ForwardRefExoticComponent<CalloutProps & React.RefAttributes<HTMLAnchorElement | HTMLButtonElement>>;
+
+interface CaptionProps {
+    as?: BoxProps['as'];
+    number?: number;
+    children: ReactNode;
+    label?: string;
+}
+declare const Caption: ({ as, number, children, label, }: CaptionProps) => React.JSX.Element;
+
+type SetClim = (setter: (prev: [number, number]) => [number, number]) => void;
+interface ColorbarProps extends FlexProps {
+    colormap: string[];
+    label?: ReactNode;
+    clim?: [number, number];
+    setClim?: SetClim;
+    setClimStep?: number;
+    units?: ReactNode;
+    width?: ThemeUICSSObject['width'];
+    height?: ThemeUICSSObject['height'];
+    format?: (d: number) => ReactNode;
+    discrete?: boolean;
+    horizontal?: boolean;
+    bottom?: boolean;
+    sxClim?: ThemeUIStyleObject;
+}
+declare const Colorbar: ({ colormap, label, clim, setClim, setClimStep, discrete, units, width, height, format, horizontal, bottom, sx, sxClim, ...props }: ColorbarProps) => React.JSX.Element;
+
+interface InlineColorProps extends BoxProps {
+    color: string;
+    children: ReactNode;
+}
+type ColorProps = Omit<InlineColorProps, 'color'>;
+declare const Primary: (props: ColorProps) => React.JSX.Element;
+declare const Secondary: (props: ColorProps) => React.JSX.Element;
+declare const Background: (props: ColorProps) => React.JSX.Element;
+declare const Red: (props: ColorProps) => React.JSX.Element;
+declare const Orange: (props: ColorProps) => React.JSX.Element;
+declare const Yellow: (props: ColorProps) => React.JSX.Element;
+declare const Green: (props: ColorProps) => React.JSX.Element;
+declare const Teal: (props: ColorProps) => React.JSX.Element;
+declare const Blue: (props: ColorProps) => React.JSX.Element;
+declare const Purple: (props: ColorProps) => React.JSX.Element;
+declare const Pink: (props: ColorProps) => React.JSX.Element;
+declare const Grey: (props: ColorProps) => React.JSX.Element;
+
+declare const colors_Background: typeof Background;
+declare const colors_Blue: typeof Blue;
+declare const colors_Green: typeof Green;
+declare const colors_Grey: typeof Grey;
+declare const colors_Orange: typeof Orange;
+declare const colors_Pink: typeof Pink;
+declare const colors_Primary: typeof Primary;
+declare const colors_Purple: typeof Purple;
+declare const colors_Red: typeof Red;
+declare const colors_Secondary: typeof Secondary;
+declare const colors_Teal: typeof Teal;
+declare const colors_Yellow: typeof Yellow;
+declare namespace colors {
+  export { colors_Background as Background, colors_Blue as Blue, colors_Green as Green, colors_Grey as Grey, colors_Orange as Orange, colors_Pink as Pink, colors_Primary as Primary, colors_Purple as Purple, colors_Red as Red, colors_Secondary as Secondary, colors_Teal as Teal, colors_Yellow as Yellow };
+}
+
+interface ColumnProps extends BoxProps {
+    start?: number | 'auto' | (number | 'auto')[];
+    width?: number | 'auto' | (number | 'auto')[];
+    dl?: 0.5 | 1;
+    dr?: 0.5 | 1;
+}
+declare const Column: ({ start, width, dl, dr, children, sx, ...props }: ColumnProps) => React.JSX.Element;
+
+declare const Custom404: () => React.JSX.Element;
+
+type DimmerProps = IconButtonProps;
+declare const Dimmer: ({ sx, ...props }: DimmerProps) => React.JSX.Element;
+
+interface ExpanderProps {
+    value: IconButtonProps['aria-checked'];
+    id?: IconButtonProps['id'];
+    onClick: IconButtonProps['onClick'];
+    sx?: IconButtonProps['sx'];
+}
+declare const Expander: ({ value, id, onClick, sx }: ExpanderProps) => React.JSX.Element;
+
+interface FadeInProps extends BoxProps {
+    duration?: number;
+    delay?: number;
+}
+declare const FadeIn: ({ duration, delay, children, ...delegated }: FadeInProps) => React.JSX.Element;
+
+interface FigureProps {
+    as?: React.ElementType;
+    children?: React.ReactNode;
+    sx?: ThemeUIStyleObject;
+}
+declare const Figure: ({ as, children, sx }: FigureProps) => React.JSX.Element;
+
+type FigureCaptionProps = CaptionProps;
+declare const FigureCaption: {
+    ({ as, number, children, }: CaptionProps): React.JSX.Element;
+    displayName: string;
+};
+
+interface FilterProps<T> extends BoxProps {
+    values: {
+        [Property in keyof T]: boolean;
+    };
+    setValues: (updated: {
+        [Property in keyof T]: boolean;
+    }) => void;
+    order?: (keyof T)[];
+    colors?: {
+        [Property in keyof T]: string;
+    };
+    labels?: {
+        [Property in keyof T]: ReactNode;
+    };
+    label?: ReactNode;
+    showAll?: boolean;
+    multiSelect?: boolean;
+}
+declare const Filter: <T>({ values, setValues, label, colors, order, labels, showAll, multiSelect, ...props }: FilterProps<T>) => React.JSX.Element;
+
+declare const Footer: () => React.JSX.Element;
+
+interface GuideProps {
+    color?: string;
+}
+declare const Guide: ({ color }: GuideProps) => React.JSX.Element;
+
+interface HeaderProps {
+    status?: string;
+    mode?: 'homepage' | 'local' | 'remote';
+    nav?: string;
+    menuItems?: ReactNode;
+}
+declare const Header: ({ status, mode, nav, menuItems }: HeaderProps) => React.JSX.Element;
+
+interface HeadingProps {
+    children: ReactNode;
+    sidenote?: ReactNode;
+    variant?: 'h1' | 'h2';
+    description?: ReactNode;
+    descriptionStart?: number[];
+    descriptionWidth?: number[];
+    sx?: ThemeUIStyleObject;
+}
+declare const Heading: ({ children, sidenote, variant, description, descriptionStart, descriptionWidth, sx, }: HeadingProps) => React.JSX.Element;
+
+interface InputProps extends Omit<React.ComponentPropsWithRef<typeof Input>, 'size'> {
+    size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    inverted?: boolean;
+}
+declare const _default$3: React.ForwardRefExoticComponent<Omit<InputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
+
+interface SettingsProps extends Omit<IconButtonProps, 'value' | 'onClick'> {
+    value: boolean;
+    onClick?: (e?: React.MouseEvent<HTMLButtonElement>) => void;
+}
+declare const Settings: ({ value, sx, ...props }: SettingsProps) => React.JSX.Element;
+
+interface LayoutProps {
+    title?: string;
+    description?: string;
+    url?: string;
+    card?: string;
+    children?: ReactNode;
+    status?: string;
+    nav?: string;
+    settings?: SettingsProps;
+    footer?: boolean;
+    header?: boolean;
+    metadata?: 'mouse' | 'scroll' | boolean;
+    links?: 'remote' | 'local' | 'homepage';
+    dimmer?: 'bottom' | 'top';
+    guide?: boolean | string;
+    scrollbar?: boolean;
+    fade?: boolean;
+    container?: boolean;
+    printable?: boolean;
+}
+declare const Layout: ({ title, description, url, card, children, status, nav, settings, footer, header, metadata, links, dimmer, guide, scrollbar, fade, container, printable, }: LayoutProps) => React.JSX.Element;
+
+interface LinkProps extends LinkProps$1 {
+    href?: string;
+    internal?: boolean;
+}
+declare const _default$2: React.ForwardRefExoticComponent<Omit<LinkProps, "ref"> & React.RefAttributes<HTMLAnchorElement>>;
+
+interface LinkGroupProps {
+    members: {
+        href: string;
+        label: string;
+    }[];
+    color?: string;
+    inverted?: boolean;
+    size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    rowGap?: ThemeUICSSObject['rowGap'];
+    columnGap?: ThemeUICSSObject['columnGap'];
+    direction?: 'horizontal' | 'vertical';
+    sx?: ThemeUIStyleObject;
+}
+declare const LinkGroup: ({ members, color, inverted, size, rowGap, columnGap, direction, sx, }: LinkGroupProps) => React.JSX.Element;
+
+type LogoProps = BoxProps;
+declare const Logo: ({ ...props }: LogoProps) => React.JSX.Element;
+
+interface MenuProps extends Omit<IconButtonProps, 'value'> {
+    value?: boolean;
+}
+declare const Menu: ({ value, sx, ...props }: MenuProps) => React.JSX.Element;
+
+interface MetaProps {
+    title?: string;
+    description?: string;
+    card?: string;
+    url?: string;
+}
+declare const Meta: ({ title, description, card, url }: MetaProps) => React.JSX.Element;
+
+interface MetadataProps {
+    mode: 'mouse' | 'scroll';
+}
+declare const Metadata: ({ mode }: MetadataProps) => React.JSX.Element;
+
+type MonogramProps = BoxProps;
+declare const Monogram: ({ ...props }: MonogramProps) => React.JSX.Element;
+
+declare const Scrollbar: () => null;
+
+interface SelectProps extends Omit<BoxProps, 'onChange'>, Omit<React.SelectHTMLAttributes<HTMLSelectElement>, keyof BoxProps | 'onChange' | 'size'> {
+    size?: 'xs' | 'sm' | 'md';
+    sxSelect?: ThemeUIStyleObject;
+    onChange?: React.ChangeEventHandler<HTMLSelectElement>;
+}
+declare const Select: ({ children, size, sx, sxSelect, onChange, ...props }: SelectProps) => React.JSX.Element;
+
+interface SidenoteProps {
+    children: ReactNode;
+    variant?: 'h1' | 'h2';
+}
+declare const Sidenote: ({ children, variant }: SidenoteProps) => React.JSX.Element;
+
+type SliderProps = React.ComponentPropsWithRef<typeof Slider>;
+declare const _default$1: React.ForwardRefExoticComponent<Omit<Omit<Omit<theme_ui.SliderProps, "ref"> & React.RefAttributes<HTMLInputElement>, "ref"> & {
+    ref?: ((instance: HTMLInputElement | null) => void | React.DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES[keyof React.DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES]) | React.RefObject<HTMLInputElement> | null | undefined;
+}, "ref"> & React.RefAttributes<HTMLInputElement>>;
+
+/**
+ * A responsive value that maps to screen breakpoints
+ * `[mobile (<40em), tablet (≥40em), desktop (≥64em), large (≥102em)]`.
+ * A single number applies to all breakpoints; an array specifies per-breakpoint values.
+ *
+ * Arrays of length 1, 2, or 4 are supported:
+ * - `[n]` — same value at all breakpoints
+ * - `[a, b]` — `a` for mobile and tablet, `b` for desktop and large
+ * - `[mobile, tablet, desktop, large]` — explicit value at each breakpoint
+ *
+ * Note: this differs from theme-ui's native responsive arrays (e.g. in `sx`),
+ * where the last value carries forward to all larger breakpoints. Here, `[a, b]`
+ * is expanded to `[a, a, b, b]` (split at 64em), whereas theme-ui would treat it
+ * as `a` below 40em and `b` at 40em+ (split at 40em).
+ */
+type ResponsiveNumber = number | number[];
+/**
+ * A table built on the CarbonPlan grid system.
+ *
+ * `start` and `width` are arrays with one entry per table column.
+ * Each entry is a {@link ResponsiveNumber} controlling that column's
+ * grid position or span.
+ *
+ * @example
+ * // 2-column table: stacked on mobile, side-by-side on tablet+
+ * // (from soil-protocols-explainer/metric-table)
+ * <Table
+ *   columns={[6]}
+ *   start={[
+ *     [1, 1, 1, 1],
+ *     [1, 3, 3, 3],
+ *   ]}
+ *   width={[
+ *     [6, 2, 2, 2],
+ *     [6, 4, 4, 4],
+ *   ]}
+ *   data={[
+ *     ['Rigor', 'Approach to quantifying soil carbon...'],
+ *     ['Additionality', 'Approach to analyzing causal relationship...'],
+ *   ]}
+ * />
+ */
+interface TableProps {
+    /**
+     * The tabular data as a 2D array: `data[row][tableColumn]`.
+     * Each inner array is a row; each element becomes a `<td>`.
+     * Elements can be strings, numbers, or React nodes.
+     */
+    data: ReactNode[][];
+    /**
+     * Total number of grid columns the table spans, as a responsive value.
+     * This is passed to the underlying `Row` component and controls the
+     * grid template, not the number of visible table columns.
+     *
+     * @example
+     * columns={[6]}              // 6 grid columns at all breakpoints
+     * columns={[4, 6, 6, 6]}    // 4 on mobile, 6 on tablet+
+     */
+    columns: ResponsiveNumber;
+    /**
+     * Grid column where each table column starts, as an array with one entry
+     * per table column. Each entry is a {@link ResponsiveNumber}.
+     *
+     * - Outer array length = number of table columns (must match `data[n].length`)
+     * - Inner value = grid column start position, optionally responsive
+     *
+     * @example
+     * // 2 table columns: stacked on mobile, side-by-side on tablet+
+     * // (from soil-protocols-explainer/metric-table)
+     * start={[
+     *   [1, 1, 1, 1],    // table col 0 starts at grid col 1 at all breakpoints
+     *   [1, 3, 3, 3],    // table col 1 starts at grid col 1 on mobile, 3 on tablet+
+     * ]}
+     *
+     * // 5 table columns: stacked on mobile, spread across grid on tablet+
+     * // (from ton-year-explainer/examples-table)
+     * start={[
+     *   [1, 1, 1, 1],    // table col 0 at grid col 1
+     *   [1, 3, 3, 3],    // table col 1 at grid col 1 on mobile, 3 on tablet+
+     *   [2, 4, 4, 4],    // table col 2 at grid col 2 on mobile, 4 on tablet+
+     *   [3, 5, 5, 5],    // ...
+     *   [4, 6, 6, 6],
+     * ]}
+     */
+    start: ResponsiveNumber[];
+    /**
+     * Number of grid columns each table column spans, as an array with one
+     * entry per table column. Each entry is a {@link ResponsiveNumber}.
+     *
+     * - Outer array length = number of table columns (must match `data[n].length`)
+     * - Inner value = grid column span, optionally responsive
+     *
+     * @example
+     * // 2 table columns: full-width on mobile, split on tablet+
+     * // (from soil-protocols-explainer/metric-table)
+     * width={[
+     *   [6, 2, 2, 2],    // table col 0 spans 6 grid cols on mobile, 2 on tablet+
+     *   [6, 4, 4, 4],    // table col 1 spans 6 grid cols on mobile, 4 on tablet+
+     * ]}
+     *
+     * // 5 table columns: label full-width on mobile, all 1-col on tablet+
+     * // (from ton-year-explainer/examples-table)
+     * width={[
+     *   [4, 2, 2, 2],    // table col 0 (label) spans 4 on mobile, 2 on tablet+
+     *   [1, 1, 1, 1],    // table cols 1-4 always span 1 grid col
+     *   [1, 1, 1, 1],
+     *   [1, 1, 1, 1],
+     *   [1, 1, 1, 1],
+     * ]}
+     */
+    width: ResponsiveNumber[];
+    /** Whether to style the first table column as an index with uppercase heading font. @default true */
+    index?: boolean;
+    /** Whether to render a border below the last row. @default true */
+    borderBottom?: boolean;
+    /** Whether to render a border above the first row. @default true */
+    borderTop?: boolean;
+    /** Theme UI style overrides applied to the outer `<table>` element. */
+    sx?: ThemeUIStyleObject;
+    /** Theme UI color for the header row text (e.g. `'secondary'`, `'orange'`). */
+    color?: string;
+    /** Content rendered in a header row above the data rows. */
+    header?: ReactNode;
+}
+declare const Table: ({ data, sx, color, header, columns, start, width, index, borderBottom, borderTop, }: TableProps) => React.JSX.Element;
+
+interface TableCaptionProps {
+    as?: BoxProps['as'];
+    number?: number;
+    children: ReactNode;
+}
+declare const TableCaption: {
+    ({ as, number, children, }: TableCaptionProps): React.JSX.Element;
+    displayName: string;
+};
+
+interface TagProps extends BoxProps, Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, keyof BoxProps | 'value'> {
+    label?: BoxProps['aria-label'];
+    value?: boolean;
+}
+declare const Tag: ({ label, value, sx, children, ...props }: TagProps) => React.JSX.Element;
+
+interface ToggleProps extends Omit<BoxProps, 'value'>, Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, keyof BoxProps | 'value'> {
+    value?: boolean;
+}
+declare const _default: React.ForwardRefExoticComponent<ToggleProps & React.RefAttributes<HTMLButtonElement>>;
+
+interface TrayProps {
+    expanded: boolean;
+    sx?: ThemeUIStyleObject;
+    children: ReactNode;
+}
+declare const Tray: ({ expanded, sx, children }: TrayProps) => React.JSX.Element;
+
+interface FormatDateOptions {
+    month?: string | boolean;
+    day?: string | boolean;
+    year?: string | boolean;
+    separator?: string;
+}
+declare const formatDate: (date: string, options?: FormatDateOptions) => string;
+
+declare const getScrollbarWidth: (document: Document) => number;
+
+declare const useScrollbarClass: () => string | null;
+
+export { Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, Badge, type BadgeProps, Blockquote, type BlockquoteProps, _default$5 as Button, type ButtonProps, _default$4 as Callout, type CalloutProps, Caption, type CaptionProps, Colorbar, type ColorbarProps, colors as Colors, Column, type ColumnProps, Custom404, Dimmer, type DimmerProps, Expander, type ExpanderProps, FadeIn, type FadeInProps, Figure, FigureCaption, type FigureCaptionProps, type FigureProps, Filter, type FilterProps, Footer, Group, type GroupProps, Guide, type GuideProps, Header, type HeaderProps, Heading, type HeadingProps, _default$3 as Input, type InputProps, Layout, type LayoutProps, _default$2 as Link, LinkGroup, type LinkGroupProps, type LinkProps, Logo, type LogoProps, Menu, type MenuProps, Meta, type MetaProps, Metadata, type MetadataProps, Monogram, type MonogramProps, Row, type RowProps, Scrollbar, Select, type SelectProps, Settings, type SettingsProps, Sidenote, type SidenoteProps, _default$1 as Slider, type SliderProps, Table, TableCaption, type TableCaptionProps, type TableProps, Tag, type TagProps, _default as Toggle, type ToggleProps, Tray, type TrayProps, formatDate, getScrollbarWidth, useScrollbarClass };