@dropby/react 0.4.0

package/dist/components/index.d.ts

@@ -0,0 +1,290 @@
+import { n as ChatAttachmentsToolkit, t as ChatAttachmentDraft } from "../chunks/chat-attachment-types-BG8VFQj5.js";
+import { ButtonHTMLAttributes, FormHTMLAttributes, HTMLAttributes, ReactNode } from "react";
+import { AskField, AsksActions, AsyncResource, ChatActions, ChatHistoryLoadState, ChatThread as ChatThread$1, ChatThreadActions, ChatThreadsCollection, DropByError, DropById, FlagValue, Idea as Idea$1, IdeasActions, ListIdeasView, PagedCollection, PendingAsk, PendingAsksCollection } from "@dropby/browser";
+/** Props for `Ask`, plus any `div` attribute. */
+interface AskProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+  /** The ask to show. */
+  ask: PendingAsk;
+  /** Passed to its `AskForm`. */
+  fieldsPerStep?: number;
+  /** Your own body, given the ask, in place of its title and form. */
+  children?: (state: {
+    ask: PendingAsk;
+  }) => ReactNode;
+}
+/** One pending ask: its title and its `AskForm`, marked `data-pending`. */
+export declare function Ask({ ask, fieldsPerStep, children, ...rest }: AskProps): import("react").JSX.Element;
+/** One field's answer: text, the chosen option ids, or a rating. */
+type AskAnswerValue = string | string[] | number;
+/** The answers given so far, by field id. */
+type AskAnswers = Record<string, AskAnswerValue>;
+/** What an `AskForm` render function receives. */
+interface AskFormState {
+  /** The ask being answered. */
+  ask: PendingAsk;
+  /** The fields on the current step. */
+  fields: AskField[];
+  /** The answers given so far. */
+  answers: AskAnswers;
+  /** Sets one field's answer, and clears its issue. */
+  setAnswer: (fieldId: string, value: AskAnswerValue) => void;
+  /** The current step, from 0. */
+  step: number;
+  /** How many steps there are. */
+  stepCount: number;
+  /** Whether this is the first step. */
+  isFirst: boolean;
+  /** Whether this is the last step. */
+  isLast: boolean;
+  /** Goes to the step before. */
+  back: () => void;
+  /** Goes to the next step when this one's answers are valid, or shows their issues. */
+  next: () => void;
+  /** Sends every answer when all are valid, or goes to the first step with an issue. */
+  submit: () => Promise<void>;
+  /** Dismisses the ask. */
+  dismiss: () => Promise<void>;
+  /** Whether a submit or dismissal is in flight. */
+  submitting: boolean;
+  /** Each field's issue, in copy for the user, by field id. */
+  issues: Record<string, string>;
+  /** Why the last submit or dismissal failed. */
+  error: DropByError | null;
+}
+/** Props for `AskForm`, plus any `form` attribute. */
+interface AskFormProps extends Omit<FormHTMLAttributes<HTMLFormElement>, "children" | "onSubmit"> {
+  /** The ask to answer. */
+  ask: PendingAsk;
+  /** How many fields a step shows: all by default, 1 for one at a time. */
+  fieldsPerStep?: number;
+  /** Your own form body, given the form's state, in place of the default. */
+  children?: (state: AskFormState) => ReactNode;
+}
+/**
+ * The form to answer one ask: its fields, in steps when `fieldsPerStep` is set,
+ * then submit, and dismiss when the ask allows it. It checks each step's answers
+ * before moving on, and shows a failed submit or dismissal in plain copy.
+ */
+export declare function AskForm({ ask, fieldsPerStep, children, ...rest }: AskFormProps): import("react").JSX.Element;
+/** What a `ChatComposer` render function receives. */
+interface ChatComposerState {
+  /** The text being written. */
+  draft: string;
+  /** Changes the text. */
+  setDraft: (value: string) => void;
+  /**
+   * Sends the draft with any ready attachments, then clears both. Does nothing
+   * when the draft is empty, a send is in flight, or an upload is still in
+   * progress.
+   */
+  send: () => Promise<void>;
+  /** Whether a send is in flight. */
+  sending: boolean;
+  /** Why the last send failed; the draft is kept to send again. */
+  error: DropByError | null;
+  /** The attachments passed in, if any. */
+  attachments: ChatAttachmentsToolkit | undefined;
+}
+/** Props for `ChatComposer`, plus any `form` attribute. */
+interface ChatComposerProps extends Omit<FormHTMLAttributes<HTMLFormElement>, "children" | "onSubmit"> {
+  /** The conversation to send to. */
+  threadId: DropById<"thr_">;
+  /**
+   * Attachments from `useChatAttachments`, in
+   * `@dropby/react/components/chat-attachments`. Omit for a text-only composer.
+   */
+  attachments?: ChatAttachmentsToolkit;
+  /** Your own form body, given the draft and `send`, in place of the default. */
+  children?: (state: ChatComposerState) => ReactNode;
+}
+/**
+ * A message box for one conversation. A message needs text, and sending is blocked
+ * while an upload is in progress; with `attachments`, it sends those that are
+ * ready. A failed send keeps the draft and shows plain copy; sending the same text
+ * and attachments again reuses the failed send's key, so a send whose answer was
+ * lost is not posted twice while this composer stays mounted.
+ */
+export declare function ChatComposer({ threadId, attachments, children, ...rest }: ChatComposerProps): import("react").JSX.Element;
+/** What a `ChatThread` render function receives. */
+interface ChatThreadState {
+  /** The load of older messages, once one started. */
+  olderMessages: ChatHistoryLoadState | undefined;
+  /** The load of the newest messages, once one started. */
+  latestMessages: ChatHistoryLoadState | undefined;
+  /** The conversation as loaded. */
+  thread: AsyncResource<ChatThread$1> | undefined;
+  /** The conversation's actions. */
+  actions: ChatThreadActions;
+}
+/** Props for `ChatThread`, plus any `div` attribute, which applies to the default body only. */
+interface ChatThreadProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+  /** The conversation to show. */
+  id: DropById<"thr_">;
+  /** Do not open the conversation on mount; call `actions.open()` yourself. */
+  manualLoad?: boolean;
+  /**
+   * Mark replies seen once they are read on screen; true by default. Pass false
+   * to call `actions.markSeen` yourself. A render function's body is never
+   * watched.
+   */
+  acknowledge?: boolean;
+  /**
+   * Your own body, given the conversation and its actions, in place of the
+   * default, composer included. A custom body is never watched for reading.
+   */
+  children?: (state: ChatThreadState) => ReactNode;
+}
+/**
+ * One conversation: its messages, each with `data-author` and any attachments, in
+ * a live region, then a text-only composer. It opens the conversation on mount
+ * unless `manualLoad`, and shows the load in `data-status`. When the thread or an
+ * element around it scrolls (`overflow-y: auto` or `scroll`), the default body
+ * follows new messages while the reader is at the end, or when the message is
+ * their own; it never scrolls the page. It marks replies seen once they are read
+ * on screen.
+ */
+export declare function ChatThread({ id, manualLoad, acknowledge, children, ...rest }: ChatThreadProps): ReactNode;
+/** What a `ChatThreadList` render function receives. */
+interface ChatThreadListState {
+  /** The conversation list. */
+  threads: ChatThreadsCollection;
+  /** Chat's actions. */
+  actions: ChatActions;
+}
+/** Props for `ChatThreadList`, plus any `ul` attribute, which applies to the default list only. */
+interface ChatThreadListProps extends Omit<HTMLAttributes<HTMLUListElement>, "children" | "onSelect"> {
+  /** Do not load the list on mount; call `actions.listThreads()` yourself. */
+  manualLoad?: boolean;
+  /** Makes each row a button that calls this with its conversation's id. */
+  onSelect?: (threadId: DropById<"thr_">) => void;
+  /** The conversation open now, marked `aria-current`; used only with `onSelect`. */
+  selectedId?: DropById<"thr_"> | null;
+  /** Your own list, given the conversations and chat's actions, in place of the default. */
+  children?: (state: ChatThreadListState) => ReactNode;
+}
+/**
+ * The user's conversations, newest first, a page at a time. It starts with a
+ * refresh button and an unread filter (`aria-pressed`), marks rows with unread
+ * replies `data-unread`, loads on mount unless `manualLoad`, shows the load in
+ * `data-status` and `data-empty`, and ends with a "show more conversations" item
+ * (`data-load-more`) while there are more, which also retries a page that failed.
+ */
+export declare function ChatThreadList({ manualLoad, onSelect, selectedId, children, ...rest }: ChatThreadListProps): ReactNode;
+/** Props for `Feature`. */
+interface FeatureProps {
+  /** The feature flag to read. */
+  name: string;
+  /** The value that turns it on; without it, any truthy value does. */
+  equals?: FlagValue;
+  /** What to render when the flag is off, unset, or not yet read. */
+  fallback?: ReactNode;
+  /** What to render when the flag is on. */
+  children: ReactNode;
+}
+/**
+ * Renders its children when a feature flag is on: equal to `equals` when given,
+ * otherwise truthy. Renders `fallback` otherwise, including until the session has
+ * loaded. It adds no markup of its own.
+ */
+export declare function Feature({ name, equals, fallback, children }: FeatureProps): ReactNode;
+/** Props for `Idea`, plus any `div` attribute. */
+interface IdeaProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+  /** The idea to show. */
+  idea: Idea$1;
+  /**
+   * A function given the idea renders your own body in place of the default; other
+   * children are added after it.
+   */
+  children?: ((state: {
+    idea: Idea$1;
+  }) => ReactNode) | ReactNode;
+}
+/**
+ * One idea: its vote button, title and description, with `data-voted` when the
+ * user voted. In your own body, use `IdeaVoteButton` for voting.
+ */
+export declare function Idea({ idea, children, ...rest }: IdeaProps): import("react").JSX.Element;
+/** What an `IdeaList` render function receives. */
+interface IdeaListState {
+  /** The ideas list. */
+  ideas: PagedCollection<Idea$1>;
+  /** The board's actions. */
+  actions: IdeasActions;
+}
+/** Props for `IdeaList`, plus any `ul` attribute, which applies to the default list only. */
+interface IdeaListProps extends Omit<HTMLAttributes<HTMLUListElement>, "children"> {
+  /**
+   * The user's ideas, or the public board; `owned` by default. Used only when the
+   * ideas store has not loaded yet; to switch later, call `actions.list({ view
+   * })`.
+   */
+  view?: ListIdeasView;
+  /** Do not load on mount; call `actions.list()` yourself. */
+  manualLoad?: boolean;
+  /** Your own list, given the ideas and the board's actions, in place of the default. */
+  children?: (state: IdeaListState) => ReactNode;
+}
+/**
+ * Ideas, each an `Idea`, a page at a time: the board by votes, the user's ideas
+ * newest first. It loads on mount unless `manualLoad`, shows the load in
+ * `data-status` and `data-empty`, and ends with a "show more ideas" item
+ * (`data-load-more`) while there are more.
+ */
+export declare function IdeaList({ view, manualLoad, children, ...rest }: IdeaListProps): ReactNode;
+/** What an `IdeaVoteButton` render function receives: one idea's vote. */
+interface IdeaVoteState {
+  /** The idea. */
+  idea: Idea$1;
+  /** Whether the user voted for it. */
+  voted: boolean;
+  /** Whether the user can vote on it. */
+  votable: boolean;
+  /** Whether a vote is in flight. */
+  voting: boolean;
+  /** Why the last vote failed. */
+  error: DropByError | null;
+  /** Adds the user's vote. */
+  vote: () => Promise<void>;
+  /** Takes the user's vote back. */
+  unvote: () => Promise<void>;
+  /** Votes, or takes the vote back. */
+  toggle: () => Promise<void>;
+}
+/** Props for `IdeaVoteButton`, plus any `button` attribute. */
+interface IdeaVoteButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children"> {
+  /** The idea to vote on. */
+  idea: Idea$1;
+  /** Your own content, or a function given the vote state, in place of the vote count. */
+  children?: ReactNode | ((state: IdeaVoteState) => ReactNode);
+}
+/**
+ * A button that votes for an idea, or takes the vote back. It shows the vote
+ * count, is disabled while a vote is in flight or when the user cannot vote, and
+ * exposes its state in `aria-pressed`, `aria-busy`, `data-voted` and `data-busy`.
+ * Your own `onClick` runs first and can cancel the vote with `preventDefault()`;
+ * your own `disabled` wins over its own.
+ */
+export declare function IdeaVoteButton({ idea, children, onClick, disabled, ...rest }: IdeaVoteButtonProps): import("react").JSX.Element;
+/** What a `PendingAsks` render function receives. */
+interface PendingAsksState {
+  /** The asks waiting for the user. */
+  asks: PendingAsksCollection;
+  /** The asks' actions. */
+  actions: AsksActions;
+}
+/** Props for `PendingAsks`, plus any `ul` attribute, which applies to the default list only. */
+interface PendingAsksProps extends Omit<HTMLAttributes<HTMLUListElement>, "children"> {
+  /** Passed to each ask's form. */
+  fieldsPerStep?: number;
+  /** Do not load on mount; call `actions.listPending()` yourself. */
+  manualLoad?: boolean;
+  /** Your own list, given the asks and their actions, in place of the default. */
+  children?: (state: PendingAsksState) => ReactNode;
+}
+/**
+ * The asks waiting for the user, each an `Ask`, a page at a time. It loads on
+ * mount unless `manualLoad`, shows the load in `data-status` and `data-empty`,
+ * and ends with a "show more asks" item (`data-load-more`) while there are more.
+ */
+export declare function PendingAsks({ fieldsPerStep, manualLoad, children, ...rest }: PendingAsksProps): ReactNode;
+export type { AskAnswerValue, AskAnswers, AskFormProps, AskFormState, AskProps, ChatAttachmentDraft, ChatAttachmentsToolkit, ChatComposerProps, ChatComposerState, ChatThreadListProps, ChatThreadListState, ChatThreadProps, ChatThreadState, FeatureProps, IdeaListProps, IdeaListState, IdeaProps, IdeaVoteButtonProps, IdeaVoteState, PendingAsksProps, PendingAsksState };