@openwarelabs/ui 0.15.0 → 0.16.0

package/dist/components/MediaPlayer/MediaPlayer.types.d.cts

@@ -0,0 +1,109 @@
+import type { CSSProperties } from "react";
+/** One file of the same media, for browsers to pick the first they can play. */
+export interface MediaPlayerSource {
+    /** The file's URL. */
+    src: string;
+    /** Its MIME type, such as "video/webm" or "audio/mpeg". It also tells the player whether it's audio or video. */
+    type?: string;
+}
+/** A captions or subtitles file (WebVTT) for a video. */
+export interface MediaPlayerTrack {
+    /** The .vtt file's URL. */
+    src: string;
+    /** Its language, such as "en". */
+    srcLang: string;
+    /** Its name in the captions menu, such as "English". */
+    label: string;
+    /** Shows these captions from the start.
+     * @default false */
+    default?: boolean;
+}
+/** What a ref to a MediaPlayer can do. */
+export interface MediaPlayerHandle {
+    /** Starts playing. Resolves once it does; rejects if the browser blocks it (autoplay rules). */
+    play(): Promise<void>;
+    pause(): void;
+    /** Goes to this many seconds in. */
+    seek(time: number): void;
+    /** The `<video>` or `<audio>` element, for anything else. */
+    readonly media: HTMLMediaElement | null;
+}
+export interface MediaPlayerLabels {
+    /** Names the player when there's no `title`. @default "Video player" or "Audio player" */
+    player?: string;
+    /** @default "Play" */
+    play?: string;
+    /** @default "Pause" */
+    pause?: string;
+    /** Names the timeline. @default "Seek" */
+    seek?: string;
+    /** @default "Volume" */
+    volume?: string;
+    /** @default "Mute" */
+    mute?: string;
+    /** @default "Unmute" */
+    unmute?: string;
+    /** Names the speed menu; its button shows the speed, like "1×". @default "Playback speed" */
+    speed?: string;
+    /** @default "Captions" */
+    captions?: string;
+    /** The captions menu's item that turns them off, when there's more than one language. @default "Off" */
+    captionsOff?: string;
+    /** @default "Full screen" */
+    fullscreen?: string;
+    /** @default "Exit full screen" */
+    exitFullscreen?: string;
+    /** @default "Picture in picture" */
+    pictureInPicture?: string;
+    /** Reads out where it is on the timeline. @default (time, duration) => `${time} of ${duration}`, as "1:05 of 3:40" */
+    position?(time: string, duration: string): string;
+}
+export interface MediaPlayerProps {
+    /** The file's URL, or several formats of it (`{ src, type }`), best first. */
+    src: string | MediaPlayerSource[];
+    /** Audio is a bar of controls; video is a picture with the controls over it. Left out, it's taken from the
+     * source's type or file extension, and is video when it can't tell. */
+    kind?: "audio" | "video";
+    /** A picture shown before a video plays. */
+    poster?: string;
+    /** What's playing. It names the player for screen readers, and an audio player shows it above the controls. */
+    title?: string;
+    /** Captions or subtitles for a video. With one, the captions button turns them on and off; with more, it opens a
+     * menu of languages. */
+    tracks?: MediaPlayerTrack[];
+    /** Starts playing as soon as it can. Browsers only allow this when it's `muted`, or after the person has
+     * interacted with the page.
+     * @default false */
+    autoPlay?: boolean;
+    /** Starts again from the beginning when it ends.
+     * @default false */
+    loop?: boolean;
+    /** Starts muted.
+     * @default false */
+    muted?: boolean;
+    /** The speeds in the speed menu; an empty list hides it.
+     * @default [0.5, 0.75, 1, 1.25, 1.5, 2] */
+    playbackRates?: number[];
+    /** A video's shape, width over height.
+     * @default 16 / 9 */
+    ratio?: number;
+    /** `minimal` keeps only play, the timeline and the time, for a small player or a short clip.
+     * @default "full" */
+    controls?: "full" | "minimal";
+    /** How much to load before it plays: `metadata` is enough to show the length.
+     * @default "metadata" */
+    preload?: "none" | "metadata" | "auto";
+    /** Called as it plays and when it's moved, with the time and the length in seconds. */
+    onTimeUpdate?(time: number, duration: number): void;
+    /** Called when it starts or stops playing. */
+    onPlayingChange?(playing: boolean): void;
+    /** Called when it reaches the end (not when it loops). */
+    onEnded?(): void;
+    /** The words it uses, for other languages. */
+    labels?: MediaPlayerLabels;
+    /** Names the player for screen readers, in place of `title`. */
+    "aria-label"?: string;
+    id?: string;
+    className?: string;
+    style?: CSSProperties;
+}

package/dist/components/MediaPlayer/MediaPlayer.types.d.ts

@@ -0,0 +1,109 @@
+import type { CSSProperties } from "react";
+/** One file of the same media, for browsers to pick the first they can play. */
+export interface MediaPlayerSource {
+    /** The file's URL. */
+    src: string;
+    /** Its MIME type, such as "video/webm" or "audio/mpeg". It also tells the player whether it's audio or video. */
+    type?: string;
+}
+/** A captions or subtitles file (WebVTT) for a video. */
+export interface MediaPlayerTrack {
+    /** The .vtt file's URL. */
+    src: string;
+    /** Its language, such as "en". */
+    srcLang: string;
+    /** Its name in the captions menu, such as "English". */
+    label: string;
+    /** Shows these captions from the start.
+     * @default false */
+    default?: boolean;
+}
+/** What a ref to a MediaPlayer can do. */
+export interface MediaPlayerHandle {
+    /** Starts playing. Resolves once it does; rejects if the browser blocks it (autoplay rules). */
+    play(): Promise<void>;
+    pause(): void;
+    /** Goes to this many seconds in. */
+    seek(time: number): void;
+    /** The `<video>` or `<audio>` element, for anything else. */
+    readonly media: HTMLMediaElement | null;
+}
+export interface MediaPlayerLabels {
+    /** Names the player when there's no `title`. @default "Video player" or "Audio player" */
+    player?: string;
+    /** @default "Play" */
+    play?: string;
+    /** @default "Pause" */
+    pause?: string;
+    /** Names the timeline. @default "Seek" */
+    seek?: string;
+    /** @default "Volume" */
+    volume?: string;
+    /** @default "Mute" */
+    mute?: string;
+    /** @default "Unmute" */
+    unmute?: string;
+    /** Names the speed menu; its button shows the speed, like "1×". @default "Playback speed" */
+    speed?: string;
+    /** @default "Captions" */
+    captions?: string;
+    /** The captions menu's item that turns them off, when there's more than one language. @default "Off" */
+    captionsOff?: string;
+    /** @default "Full screen" */
+    fullscreen?: string;
+    /** @default "Exit full screen" */
+    exitFullscreen?: string;
+    /** @default "Picture in picture" */
+    pictureInPicture?: string;
+    /** Reads out where it is on the timeline. @default (time, duration) => `${time} of ${duration}`, as "1:05 of 3:40" */
+    position?(time: string, duration: string): string;
+}
+export interface MediaPlayerProps {
+    /** The file's URL, or several formats of it (`{ src, type }`), best first. */
+    src: string | MediaPlayerSource[];
+    /** Audio is a bar of controls; video is a picture with the controls over it. Left out, it's taken from the
+     * source's type or file extension, and is video when it can't tell. */
+    kind?: "audio" | "video";
+    /** A picture shown before a video plays. */
+    poster?: string;
+    /** What's playing. It names the player for screen readers, and an audio player shows it above the controls. */
+    title?: string;
+    /** Captions or subtitles for a video. With one, the captions button turns them on and off; with more, it opens a
+     * menu of languages. */
+    tracks?: MediaPlayerTrack[];
+    /** Starts playing as soon as it can. Browsers only allow this when it's `muted`, or after the person has
+     * interacted with the page.
+     * @default false */
+    autoPlay?: boolean;
+    /** Starts again from the beginning when it ends.
+     * @default false */
+    loop?: boolean;
+    /** Starts muted.
+     * @default false */
+    muted?: boolean;
+    /** The speeds in the speed menu; an empty list hides it.
+     * @default [0.5, 0.75, 1, 1.25, 1.5, 2] */
+    playbackRates?: number[];
+    /** A video's shape, width over height.
+     * @default 16 / 9 */
+    ratio?: number;
+    /** `minimal` keeps only play, the timeline and the time, for a small player or a short clip.
+     * @default "full" */
+    controls?: "full" | "minimal";
+    /** How much to load before it plays: `metadata` is enough to show the length.
+     * @default "metadata" */
+    preload?: "none" | "metadata" | "auto";
+    /** Called as it plays and when it's moved, with the time and the length in seconds. */
+    onTimeUpdate?(time: number, duration: number): void;
+    /** Called when it starts or stops playing. */
+    onPlayingChange?(playing: boolean): void;
+    /** Called when it reaches the end (not when it loops). */
+    onEnded?(): void;
+    /** The words it uses, for other languages. */
+    labels?: MediaPlayerLabels;
+    /** Names the player for screen readers, in place of `title`. */
+    "aria-label"?: string;
+    id?: string;
+    className?: string;
+    style?: CSSProperties;
+}

package/dist/components/MentionInput/MentionInput.d.cts

@@ -0,0 +1,9 @@
+import type { MentionInputProps } from "./MentionInput.types.cjs";
+export type { Mention, MentionInputProps, MentionLabels, MentionOption, MentionTrigger, UseMentionsOptions, UseMentionsResult } from "./MentionInput.types.cjs";
+export { useMentions } from "./useMentions.cjs";
+/**
+ * A text field that suggests people after `@` and commands after `/` (or any trigger you give), at the caret.
+ * Picking one puts it in the text as "@Ada Lovelace ", and `onMentionsChange` reports the mentions with their ids.
+ * One line by default; `multiline` makes it a Textarea that grows. For another text box, use `useMentions`.
+ */
+export declare const MentionInput: import("react").ForwardRefExoticComponent<MentionInputProps & import("react").RefAttributes<HTMLTextAreaElement | HTMLInputElement>>;

package/dist/components/MentionInput/MentionInput.d.ts

@@ -0,0 +1,9 @@
+import type { MentionInputProps } from "./MentionInput.types.js";
+export type { Mention, MentionInputProps, MentionLabels, MentionOption, MentionTrigger, UseMentionsOptions, UseMentionsResult } from "./MentionInput.types.js";
+export { useMentions } from "./useMentions.js";
+/**
+ * A text field that suggests people after `@` and commands after `/` (or any trigger you give), at the caret.
+ * Picking one puts it in the text as "@Ada Lovelace ", and `onMentionsChange` reports the mentions with their ids.
+ * One line by default; `multiline` makes it a Textarea that grows. For another text box, use `useMentions`.
+ */
+export declare const MentionInput: import("react").ForwardRefExoticComponent<MentionInputProps & import("react").RefAttributes<HTMLTextAreaElement | HTMLInputElement>>;

package/dist/components/MentionInput/MentionInput.types.d.cts

@@ -0,0 +1,125 @@
+import type { KeyboardEvent, ReactNode, RefCallback } from "react";
+export interface MentionOption {
+    /** Identifies what was picked, in `mentions`: a user id, a command name. */
+    id: string;
+    /** The text shown in the list, matched as people type, and put in the text after the trigger: "@Ada Lovelace". */
+    label: string;
+    /** A muted line under the label in the list; matched too when it's a string. */
+    description?: ReactNode;
+    /** A small icon or avatar before the label. */
+    icon?: ReactNode;
+    disabled?: boolean;
+}
+export interface MentionTrigger {
+    /** What opens the list when it's typed at the start of a word: "@", "/", "#". */
+    char: string;
+    /**
+     * What to suggest. A list is filtered by what's typed after the trigger. A function gets that text and returns
+     * the options to show, itself or in a promise (to search a server); the list shows a spinner while it waits.
+     */
+    options: MentionOption[] | ((query: string) => MentionOption[] | Promise<MentionOption[]>);
+    /** Called after an option is put in the text. */
+    onSelect?(option: MentionOption): void;
+    /** Draws an option's row in the list in place of its icon, label and description. */
+    render?(option: MentionOption): ReactNode;
+    /** Names the list for screen readers while this trigger has it open, such as "People".
+     * @default labels.suggestions */
+    label?: string;
+}
+/** A mention in the text, found from the options picked (and every option of a trigger with a list). */
+export interface Mention {
+    /** The option's id. */
+    id: string;
+    label: string;
+    /** The trigger it was typed with: "@". */
+    trigger: string;
+    /** Where it starts in the text, at the trigger. */
+    start: number;
+    /** Where it ends, after the label. */
+    end: number;
+}
+/** The words it uses, for other languages. */
+export interface MentionLabels {
+    /** Names the list when its trigger has no `label`. @default "Suggestions" */
+    suggestions?: string;
+    /** Shown and read out while options load. @default "Loading…" */
+    loading?: string;
+    /** Shown and read out when nothing matches. @default "No matches" */
+    empty?: string;
+    /** Read out with the number of options. @default (count) => `${count} results` */
+    results?(count: number): string;
+}
+export interface UseMentionsOptions {
+    triggers: MentionTrigger[];
+    /** The text, when you control it, so `mentions` follows changes made from outside (clearing it after a send).
+     * Without it, the hook reads the text box as people type. */
+    value?: string;
+    /** Called with the mentions in the text when they change. */
+    onMentionsChange?(mentions: Mention[]): void;
+    /** Turns the suggestions off.
+     * @default false */
+    disabled?: boolean;
+    /** The list's rows: md 36px, sm 32px.
+     * @default "md" */
+    size?: "sm" | "md";
+    labels?: MentionLabels;
+}
+export interface UseMentionsResult {
+    /** Put on the text box: a <textarea> or <input>, a Textarea, an Input, or PromptInput (its ref is the textarea). */
+    ref: RefCallback<HTMLTextAreaElement | HTMLInputElement>;
+    /** Render it anywhere, such as right after the text box: the floating list and its live region. */
+    list: ReactNode;
+    /** The mentions in the text, in order. */
+    mentions: Mention[];
+    /** Whether the list is open. */
+    isOpen: boolean;
+}
+export interface MentionInputProps {
+    /** The characters that open suggestions, with their options. */
+    triggers: MentionTrigger[];
+    /** The text, when you control it. */
+    value?: string;
+    /** The text at first, when it controls it itself.
+     * @default "" */
+    defaultValue?: string;
+    /** Called with the text on every change. */
+    onChange?(value: string): void;
+    /** Called with the mentions in the text when they change: each one's id, label, trigger and place. */
+    onMentionsChange?(mentions: Mention[]): void;
+    /** A Textarea that grows with its text, in place of a one-line Input.
+     * @default false */
+    multiline?: boolean;
+    /** The rows a multiline box shows when it's empty.
+     * @default 3 */
+    rows?: number;
+    /** The tallest a multiline box grows before it scrolls. A number is pixels.
+     * @default 180 */
+    maxHeight?: number | string;
+    placeholder?: string;
+    /** The text box and the list: sm 32px for toolbars, md 40px in forms. A multiline box keeps its own size.
+     * @default "md" */
+    size?: "sm" | "md";
+    /** Shows the field as wrong. Field sets it when there's an error.
+     * @default false */
+    isInvalid?: boolean;
+    /** @default false */
+    disabled?: boolean;
+    /** Submits the text under this name, so a Form or a plain form sends it. */
+    name?: string;
+    /** The text box's id, which a Field's label points at. */
+    id?: string;
+    autoFocus?: boolean;
+    /** Called for each key the open list doesn't take, such as Enter to send while it's closed. */
+    onKeyDown?(event: KeyboardEvent<HTMLTextAreaElement | HTMLInputElement>): void;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    labels?: MentionLabels;
+    className?: string;
+}
+/** The trigger being typed: which one, where it starts, and the text after it. Internal. */
+export interface MentionMatch {
+    trigger: MentionTrigger;
+    start: number;
+    query: string;
+}

package/dist/components/MentionInput/MentionInput.types.d.ts

@@ -0,0 +1,125 @@
+import type { KeyboardEvent, ReactNode, RefCallback } from "react";
+export interface MentionOption {
+    /** Identifies what was picked, in `mentions`: a user id, a command name. */
+    id: string;
+    /** The text shown in the list, matched as people type, and put in the text after the trigger: "@Ada Lovelace". */
+    label: string;
+    /** A muted line under the label in the list; matched too when it's a string. */
+    description?: ReactNode;
+    /** A small icon or avatar before the label. */
+    icon?: ReactNode;
+    disabled?: boolean;
+}
+export interface MentionTrigger {
+    /** What opens the list when it's typed at the start of a word: "@", "/", "#". */
+    char: string;
+    /**
+     * What to suggest. A list is filtered by what's typed after the trigger. A function gets that text and returns
+     * the options to show, itself or in a promise (to search a server); the list shows a spinner while it waits.
+     */
+    options: MentionOption[] | ((query: string) => MentionOption[] | Promise<MentionOption[]>);
+    /** Called after an option is put in the text. */
+    onSelect?(option: MentionOption): void;
+    /** Draws an option's row in the list in place of its icon, label and description. */
+    render?(option: MentionOption): ReactNode;
+    /** Names the list for screen readers while this trigger has it open, such as "People".
+     * @default labels.suggestions */
+    label?: string;
+}
+/** A mention in the text, found from the options picked (and every option of a trigger with a list). */
+export interface Mention {
+    /** The option's id. */
+    id: string;
+    label: string;
+    /** The trigger it was typed with: "@". */
+    trigger: string;
+    /** Where it starts in the text, at the trigger. */
+    start: number;
+    /** Where it ends, after the label. */
+    end: number;
+}
+/** The words it uses, for other languages. */
+export interface MentionLabels {
+    /** Names the list when its trigger has no `label`. @default "Suggestions" */
+    suggestions?: string;
+    /** Shown and read out while options load. @default "Loading…" */
+    loading?: string;
+    /** Shown and read out when nothing matches. @default "No matches" */
+    empty?: string;
+    /** Read out with the number of options. @default (count) => `${count} results` */
+    results?(count: number): string;
+}
+export interface UseMentionsOptions {
+    triggers: MentionTrigger[];
+    /** The text, when you control it, so `mentions` follows changes made from outside (clearing it after a send).
+     * Without it, the hook reads the text box as people type. */
+    value?: string;
+    /** Called with the mentions in the text when they change. */
+    onMentionsChange?(mentions: Mention[]): void;
+    /** Turns the suggestions off.
+     * @default false */
+    disabled?: boolean;
+    /** The list's rows: md 36px, sm 32px.
+     * @default "md" */
+    size?: "sm" | "md";
+    labels?: MentionLabels;
+}
+export interface UseMentionsResult {
+    /** Put on the text box: a <textarea> or <input>, a Textarea, an Input, or PromptInput (its ref is the textarea). */
+    ref: RefCallback<HTMLTextAreaElement | HTMLInputElement>;
+    /** Render it anywhere, such as right after the text box: the floating list and its live region. */
+    list: ReactNode;
+    /** The mentions in the text, in order. */
+    mentions: Mention[];
+    /** Whether the list is open. */
+    isOpen: boolean;
+}
+export interface MentionInputProps {
+    /** The characters that open suggestions, with their options. */
+    triggers: MentionTrigger[];
+    /** The text, when you control it. */
+    value?: string;
+    /** The text at first, when it controls it itself.
+     * @default "" */
+    defaultValue?: string;
+    /** Called with the text on every change. */
+    onChange?(value: string): void;
+    /** Called with the mentions in the text when they change: each one's id, label, trigger and place. */
+    onMentionsChange?(mentions: Mention[]): void;
+    /** A Textarea that grows with its text, in place of a one-line Input.
+     * @default false */
+    multiline?: boolean;
+    /** The rows a multiline box shows when it's empty.
+     * @default 3 */
+    rows?: number;
+    /** The tallest a multiline box grows before it scrolls. A number is pixels.
+     * @default 180 */
+    maxHeight?: number | string;
+    placeholder?: string;
+    /** The text box and the list: sm 32px for toolbars, md 40px in forms. A multiline box keeps its own size.
+     * @default "md" */
+    size?: "sm" | "md";
+    /** Shows the field as wrong. Field sets it when there's an error.
+     * @default false */
+    isInvalid?: boolean;
+    /** @default false */
+    disabled?: boolean;
+    /** Submits the text under this name, so a Form or a plain form sends it. */
+    name?: string;
+    /** The text box's id, which a Field's label points at. */
+    id?: string;
+    autoFocus?: boolean;
+    /** Called for each key the open list doesn't take, such as Enter to send while it's closed. */
+    onKeyDown?(event: KeyboardEvent<HTMLTextAreaElement | HTMLInputElement>): void;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    labels?: MentionLabels;
+    className?: string;
+}
+/** The trigger being typed: which one, where it starts, and the text after it. Internal. */
+export interface MentionMatch {
+    trigger: MentionTrigger;
+    start: number;
+    query: string;
+}

package/dist/components/MentionInput/useMentions.d.cts

@@ -0,0 +1,8 @@
+import type { UseMentionsOptions, UseMentionsResult } from "./MentionInput.types.cjs";
+/**
+ * `@` mentions and `/` commands for any text box. Put `ref` on a textarea or input (a Textarea, an Input, or
+ * PromptInput) and render `list`: typing a trigger at the start of a word opens suggestions at the caret, and picking
+ * one puts "@Label " in the text. The box becomes a combobox; the hook listens to it directly, so the component that
+ * owns it needs no changes.
+ */
+export declare function useMentions({ triggers, value, onMentionsChange, disabled, size, labels }: UseMentionsOptions): UseMentionsResult;

package/dist/components/MentionInput/useMentions.d.ts

@@ -0,0 +1,8 @@
+import type { UseMentionsOptions, UseMentionsResult } from "./MentionInput.types.js";
+/**
+ * `@` mentions and `/` commands for any text box. Put `ref` on a textarea or input (a Textarea, an Input, or
+ * PromptInput) and render `list`: typing a trigger at the start of a word opens suggestions at the caret, and picking
+ * one puts "@Label " in the text. The box becomes a combobox; the hook listens to it directly, so the component that
+ * owns it needs no changes.
+ */
+export declare function useMentions({ triggers, value, onMentionsChange, disabled, size, labels }: UseMentionsOptions): UseMentionsResult;

package/dist/components/NotificationCenter/NotificationCenter.d.cts

@@ -0,0 +1,12 @@
+import type { NotificationCenterProps, NotificationListProps } from "./NotificationCenter.types.cjs";
+export type { NotificationCenterProps, NotificationFilter, NotificationItem, NotificationLabels, NotificationListProps, } from "./NotificationCenter.types.cjs";
+/**
+ * The notifications as a list, newest first, optionally under Today, Yesterday and Earlier. NotificationCenter shows it
+ * in its popover; use it on its own for a full page of them.
+ */
+export declare function NotificationList({ items, onRead, onDismiss, onItemClick, groupByDay, empty, locale, labels, "aria-label": ariaLabel, className, }: NotificationListProps): import("react").JSX.Element;
+/**
+ * A bell with the unread count that opens the latest notifications in a popover: All and Unread tabs, "Mark all as
+ * read", and a footer for a link to the full page. New ones that arrive while it's closed are announced once.
+ */
+export declare function NotificationCenter({ items, onRead, onReadAll, onDismiss, onItemClick, open, defaultOpen, onOpenChange, tabs, filter, defaultFilter, onFilterChange, footer, empty, maxCount, trigger, width, groupByDay, locale, labels, className, }: NotificationCenterProps): import("react").JSX.Element;

package/dist/components/NotificationCenter/NotificationCenter.d.ts

@@ -0,0 +1,12 @@
+import type { NotificationCenterProps, NotificationListProps } from "./NotificationCenter.types.js";
+export type { NotificationCenterProps, NotificationFilter, NotificationItem, NotificationLabels, NotificationListProps, } from "./NotificationCenter.types.js";
+/**
+ * The notifications as a list, newest first, optionally under Today, Yesterday and Earlier. NotificationCenter shows it
+ * in its popover; use it on its own for a full page of them.
+ */
+export declare function NotificationList({ items, onRead, onDismiss, onItemClick, groupByDay, empty, locale, labels, "aria-label": ariaLabel, className, }: NotificationListProps): import("react").JSX.Element;
+/**
+ * A bell with the unread count that opens the latest notifications in a popover: All and Unread tabs, "Mark all as
+ * read", and a footer for a link to the full page. New ones that arrive while it's closed are announced once.
+ */
+export declare function NotificationCenter({ items, onRead, onReadAll, onDismiss, onItemClick, open, defaultOpen, onOpenChange, tabs, filter, defaultFilter, onFilterChange, footer, empty, maxCount, trigger, width, groupByDay, locale, labels, className, }: NotificationCenterProps): import("react").JSX.Element;

package/dist/components/NotificationCenter/NotificationCenter.types.d.cts

@@ -0,0 +1,129 @@
+import type { MouseEvent, ReactElement, ReactNode } from "react";
+export interface NotificationItem {
+    /** Unique among the items. */
+    id: string;
+    /** What happened, in a line: "Clara mentioned you in Pricing". It names the item for screen readers. */
+    title: ReactNode;
+    /** A second line: a quote, or where it happened. */
+    description?: ReactNode;
+    /** When it happened: a Date or an ISO string. It shows as "5 min ago", with the full date on hover. */
+    time: Date | string;
+    /** Seen already. Unread items are bold, with a dot and a hidden "Unread" for screen readers. */
+    read?: boolean;
+    /** Who it's from, usually an `<Avatar>`. Hidden from screen readers: say who in the title. */
+    avatar?: ReactNode;
+    /** A 16px icon on a round tile, for things no person did (a deploy, a reminder), when there's no avatar. */
+    icon?: ReactNode;
+    /** Makes the item a link to what it's about. Without it, the item is a button. */
+    href?: string;
+    /** A button or two beside the item, such as Accept and Decline. They sit outside the item's own link. */
+    actions?: ReactNode;
+    /** The heading it's listed under. Set it to group by your own sections; it wins over `groupByDay`. */
+    group?: string;
+}
+export interface NotificationLabels {
+    /** The popover's heading and name. @default "Notifications" */
+    title?: string;
+    /** The bell's name with the count. @default (unread) => unread ? `Notifications, ${unread} unread` : "Notifications" */
+    trigger?(unread: number): string;
+    /** @default "Mark all as read" */
+    markAllRead?: string;
+    /** The tab list's name. @default "Show" */
+    filter?: string;
+    /** @default "All" */
+    all?: string;
+    /** @default "Unread" */
+    unreadTab?: string;
+    /** Read before each unread item. @default "Unread" */
+    unread?: string;
+    /** The ✕ on each item, followed by its title. @default "Dismiss" */
+    dismiss?: string;
+    /** Said once when new ones arrive while it's closed. @default (count) => count === 1 ? "1 new notification" : `${count} new notifications` */
+    announce?(count: number): string;
+    /** @default "Today" */
+    today?: string;
+    /** @default "Yesterday" */
+    yesterday?: string;
+    /** @default "Earlier" */
+    earlier?: string;
+    /** The empty list's title. @default "You're all caught up" */
+    empty?: string;
+    /** The empty Unread tab's title. @default "No unread notifications" */
+    emptyUnread?: string;
+}
+export interface NotificationListProps {
+    /** The notifications, newest first. */
+    items: NotificationItem[];
+    /** Called with an unread item's id when it's opened. */
+    onRead?(id: string): void;
+    /** Shows a ✕ on each item that calls this with its id; remove the item from `items`. */
+    onDismiss?(id: string): void;
+    /** Called when an item is clicked, before its link is followed. */
+    onItemClick?(item: NotificationItem, event: MouseEvent<HTMLElement>): void;
+    /** Lists the items under Today, Yesterday and Earlier. An item's own `group` wins.
+     * @default false */
+    groupByDay?: boolean;
+    /** What shows when there are no items.
+     * @default an EmptyState saying "You're all caught up" */
+    empty?: ReactNode;
+    /** The locale for "5 min ago" and dates. Defaults to the browser's. */
+    locale?: string;
+    /** The words it uses, for other languages. */
+    labels?: NotificationLabels;
+    /** Names the list for screen readers, when it has no heading of its own. */
+    "aria-label"?: string;
+    className?: string;
+}
+export interface NotificationCenterProps extends Omit<NotificationListProps, "aria-label"> {
+    /** Called when "Mark all as read" is pressed; mark every item read. */
+    onReadAll?(): void;
+    /** Shown, when you control it. */
+    open?: boolean;
+    /** Shown at first, when it controls itself. Opened on load, it doesn't pull focus into it.
+     * @default false */
+    defaultOpen?: boolean;
+    /** Called when it opens or closes. */
+    onOpenChange?(open: boolean): void;
+    /** All and Unread tabs above the list.
+     * @default true */
+    tabs?: boolean;
+    /** The tab showing, when you control it. */
+    filter?: NotificationFilter;
+    /** The tab it starts on, when it controls itself.
+     * @default "all" */
+    defaultFilter?: NotificationFilter;
+    /** Called when the tab changes. */
+    onFilterChange?(filter: NotificationFilter): void;
+    /** Under the list, such as a "View all" link to a full page. */
+    footer?: ReactNode;
+    /** The badge shows "9+" above this.
+     * @default 9 */
+    maxCount?: number;
+    /** Your own button in place of the bell. Give it an aria-label with the unread count. */
+    trigger?: ReactElement;
+    /** Pixels, or any CSS width. It never gets wider than the window, less a margin.
+     * @default 380 */
+    width?: number | string;
+}
+/** Which items a NotificationCenter lists. */
+export type NotificationFilter = "all" | "unread";
+/** Internal: a run of items under one heading. */
+export interface NotificationGroup {
+    key: string;
+    label?: string;
+    items: NotificationItem[];
+}
+/** Internal: one row of the list. */
+export interface NotificationRowProps {
+    item: NotificationItem;
+    /** "5 min ago", or the date when it's older than a week. */
+    relative: string;
+    /** The full date and time, for the hover title. */
+    full: string;
+    /** The machine-readable time, for `<time dateTime>`. */
+    iso?: string;
+    labels: NotificationLabels;
+    onRead?(id: string): void;
+    onDismiss?(id: string): void;
+    onItemClick?(item: NotificationItem, event: MouseEvent<HTMLElement>): void;
+}