@fewchurs/react 0.0.0-stage → 1.0.1

package/dist/index.d.mts

@@ -0,0 +1,523 @@
+import { ReactNode, CSSProperties } from 'react';
+
+type FewchursError = {
+    code: "invalid_key";
+    status: 401;
+    message: string;
+} | {
+    code: "validation_failed";
+    status: 400;
+    message: string;
+} | {
+    code: "rate_limited";
+    status: 429;
+    message: string;
+} | {
+    code: "not_found";
+    status: 404;
+    message: string;
+} | {
+    code: "limit_reached";
+    status: 402;
+    message: string;
+} | {
+    code: "server";
+    status: number;
+    message: string;
+} | {
+    code: "network";
+    message: string;
+};
+type Result<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: FewchursError;
+};
+/** Safe to show a visitor: never leaks a server message that may name internals. */
+declare function userMessage(error: FewchursError): string;
+declare function networkError(message?: string): FewchursError;
+declare function validationError(message: string): FewchursError;
+declare function errorFromResponse(status: number, body: unknown): FewchursError;
+
+/** A status the server does not know about yet still renders, as `"unknown"`. */
+type FeatureStatus = "open" | "planned" | "in_progress" | "done" | "declined" | "unknown";
+type FeatureSort = "top" | "new";
+interface Feature {
+    id: string;
+    title: string;
+    description: string;
+    status: FeatureStatus;
+    upvoteCount: number;
+    commentCount: number;
+    followerCount: number;
+    hasVoted: boolean;
+    isFollowing: boolean;
+    isMine: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Comment {
+    id: string;
+    text: string;
+    authorName: string;
+    isDeveloper: boolean;
+    isMine: boolean;
+    createdAt: string;
+}
+interface FeaturePage {
+    features: Feature[];
+    nextCursor: string | null;
+}
+interface CommentPage {
+    comments: Comment[];
+    nextCursor: string | null;
+}
+interface FewchursConfig {
+    showBranding: boolean;
+    hideVoteCounts: boolean;
+    appName: string | null;
+}
+interface SubmitFeatureInput {
+    title: string;
+    description?: string;
+    email?: string;
+    isSubscriber?: boolean;
+}
+interface CreateCommentInput {
+    featureId: string;
+    text: string;
+    authorName?: string;
+}
+interface ListFeaturesParams {
+    sort?: FeatureSort;
+    limit?: number;
+    cursor?: string | null;
+    status?: FeatureStatus[];
+}
+interface ListCommentsParams {
+    limit?: number;
+    cursor?: string | null;
+}
+
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+interface FewchursClientOptions {
+    /** Server-side, or in a SPA where the key is publishable. Omit when calling your own proxy. */
+    apiKey?: string;
+    /** `https://www.fewchurs.com/api/v1` by default, or a proxy path such as `/api/fewchurs`. */
+    baseUrl?: string;
+    deviceId?: string | null | (() => string | null);
+    /** Sent as `Accept-Language`, so server-side copy and emails match the visitor. */
+    language?: string;
+    fetch?: FetchLike;
+    retries?: number;
+    retryDelayMs?: number;
+}
+interface FewchursClient {
+    readonly baseUrl: string;
+    getDeviceId(): string | null;
+    getConfig(signal?: AbortSignal): Promise<Result<FewchursConfig>>;
+    listFeatures(params?: ListFeaturesParams, signal?: AbortSignal): Promise<Result<FeaturePage>>;
+    getFeature(featureId: string, signal?: AbortSignal): Promise<Result<Feature>>;
+    submitFeature(input: SubmitFeatureInput): Promise<Result<Feature>>;
+    vote(featureId: string): Promise<Result<{
+        upvoteCount: number;
+        hasVoted: boolean;
+    }>>;
+    unvote(featureId: string): Promise<Result<{
+        upvoteCount: number;
+        hasVoted: boolean;
+    }>>;
+    follow(featureId: string, email: string): Promise<Result<{
+        following: boolean;
+    }>>;
+    unfollow(featureId: string): Promise<Result<{
+        following: boolean;
+    }>>;
+    listComments(featureId: string, params?: ListCommentsParams, signal?: AbortSignal): Promise<Result<CommentPage>>;
+    createComment(input: CreateCommentInput): Promise<Result<Comment>>;
+}
+declare function createFewchursClient(options?: FewchursClientOptions): FewchursClient;
+
+interface ListQuery {
+    sort: FeatureSort;
+    status?: FeatureStatus[];
+}
+declare function listKey({ sort, status }: ListQuery): string;
+/**
+ * One feature, fetched by id, kept in `lists` beside the real lists. That way a deep-linked
+ * request goes through the same vote, comment and follow updates as a row in a list.
+ */
+declare function featureKey(featureId: string): string;
+
+type LoadStatus = "idle" | "loading" | "loadingMore" | "ready" | "error";
+interface ListState {
+    features: Feature[];
+    cursor: string | null;
+    status: LoadStatus;
+    error: FewchursError | null;
+}
+interface CommentsState {
+    comments: Comment[];
+    cursor: string | null;
+    status: LoadStatus;
+    error: FewchursError | null;
+}
+interface StoreState {
+    config: FewchursConfig | null;
+    lists: Record<string, ListState>;
+    comments: Record<string, CommentsState>;
+}
+type FewchursEventName = "boardOpened" | "featureSubmitted" | "voted" | "commented" | "followed" | "error";
+interface FewchursEvent {
+    name: FewchursEventName;
+    featureId?: string;
+    hasVoted?: boolean;
+    following?: boolean;
+    error?: FewchursError;
+}
+type EventHandler = (event: FewchursEvent) => void;
+interface StoreOptions {
+    pageSize?: number;
+    initialState?: Partial<StoreState>;
+    onEvent?: EventHandler;
+}
+interface Store {
+    subscribe(listener: () => void): () => void;
+    getState(): StoreState;
+    ensureConfig(): void;
+    ensureFeatures(query: ListQuery, pageSize?: number): void;
+    ensureFeature(featureId: string): void;
+    refreshFeature(featureId: string): Promise<void>;
+    refresh(query: ListQuery, pageSize?: number): Promise<void>;
+    loadMore(query: ListQuery, pageSize?: number): Promise<void>;
+    ensureComments(featureId: string): void;
+    refreshComments(featureId: string): Promise<void>;
+    loadMoreComments(featureId: string): Promise<void>;
+    toggleVote(featureId: string): Promise<Result<{
+        upvoteCount: number;
+        hasVoted: boolean;
+    }>>;
+    submitFeature(input: SubmitFeatureInput): Promise<Result<Feature>>;
+    addComment(input: CreateCommentInput): Promise<Result<Comment>>;
+    setFollowing(featureId: string, email: string | null): Promise<Result<{
+        following: boolean;
+    }>>;
+    emit(event: FewchursEvent): void;
+}
+declare function createStore(client: FewchursClient, { pageSize, initialState, onEvent }?: StoreOptions): Store;
+declare function listStateOf(state: StoreState, key: string): ListState;
+declare function commentsStateOf(state: StoreState, featureId: string): CommentsState;
+
+interface FewchursContextValue {
+    client: FewchursClient;
+    store: Store;
+    deviceId: string | null;
+    /** False only while a direct-to-API board is still waiting for its device id. */
+    isReady: boolean;
+}
+interface FewchursProviderProps {
+    /** Publishable key for direct API calls. Omit when `baseUrl` points at your own proxy. */
+    apiKey?: string;
+    baseUrl?: string;
+    /** A stable per-visitor id — hash it if it comes from your auth. */
+    deviceId?: string;
+    language?: string;
+    pageSize?: number;
+    /** Server-rendered data, so the first paint has real content. Set by `@fewchurs/next`. */
+    initialState?: Partial<StoreState>;
+    onEvent?: EventHandler;
+    client?: FewchursClient;
+    children: ReactNode;
+}
+declare function FewchursProvider({ apiKey, baseUrl, deviceId: deviceIdProp, language, pageSize, initialState, onEvent, client: clientProp, children, }: FewchursProviderProps): React.JSX.Element;
+declare function useFewchurs(): FewchursContextValue;
+
+interface BoardLabels {
+    title: string;
+    tabTop: string;
+    tabNew: string;
+    tabRoadmap: string;
+    newRequest: string;
+    cancel: string;
+    submit: string;
+    submitting: string;
+    submitted: string;
+    fieldTitle: string;
+    fieldTitlePlaceholder: string;
+    fieldDescription: string;
+    fieldDescriptionPlaceholder: string;
+    fieldEmail: string;
+    fieldEmailHint: string;
+    fieldName: string;
+    emptyTitle: string;
+    emptyBody: string;
+    loading: string;
+    loadMore: string;
+    retry: string;
+    comments: string;
+    commentPlaceholder: string;
+    postComment: string;
+    noComments: string;
+    follow: string;
+    following: string;
+    followPlaceholder: string;
+    developer: string;
+    poweredBy: string;
+    upvote: string;
+    status: Record<FeatureStatus, string>;
+}
+declare const DEFAULT_LABELS: BoardLabels;
+declare function mergeLabels(overrides?: Partial<BoardLabels>): BoardLabels;
+
+type BoardTab = FeatureSort | "roadmap";
+type EmailFieldMode = "off" | "optional" | "required";
+interface FeatureActions {
+    toggleVote: () => Promise<void>;
+    follow: (email: string) => Promise<boolean>;
+    unfollow: () => Promise<boolean>;
+}
+interface BoardContextValue {
+    labels: BoardLabels;
+    unstyled: boolean;
+    allowComments: boolean;
+    emailField: EmailFieldMode;
+    showDeclined: boolean;
+    hideVoteCounts: boolean;
+    pageSize?: number;
+    userEmail?: string;
+    isSubscriber: boolean;
+    tab: BoardTab;
+    setTab: (tab: BoardTab) => void;
+    tabs: BoardTab[];
+    /** A request to show above the list, for a deep link into the board. */
+    initialFeatureId?: string;
+    isFormOpen: boolean;
+    setFormOpen: (open: boolean) => void;
+    /** Survives the submit form closing, so the confirmation is not unmounted with it. */
+    justSubmitted: boolean;
+    setJustSubmitted: (submitted: boolean) => void;
+    renderFeature?: (feature: Feature, actions: FeatureActions) => React.ReactNode;
+    renderEmpty?: () => React.ReactNode;
+    renderHeader?: () => React.ReactNode;
+    /** Returns a class name, or undefined in unstyled mode. */
+    cx: (...names: string[]) => string | undefined;
+}
+declare function useBoard(): BoardContextValue;
+
+declare function Branding(): React.JSX.Element | null;
+
+declare const SDK_VERSION = "1.0.1";
+
+declare const SDK_HEADER = "react/1.0.1";
+declare const DEFAULT_BASE_URL = "https://www.fewchurs.com/api/v1";
+declare const DEFAULT_PAGE_SIZE = 20;
+/** Mirrors the server's zod schemas, so the UI can reject input before a round trip. */
+declare const LIMITS: {
+    readonly titleMin: 3;
+    readonly titleMax: 100;
+    readonly descriptionMax: 1000;
+    readonly commentMin: 1;
+    readonly commentMax: 1000;
+    readonly authorNameMax: 60;
+};
+/** What the Roadmap tab asks for, and what it keeps if the server ignores the filter. */
+declare const ROADMAP_STATUSES: FeatureStatus[];
+
+declare function FeatureList(): React.JSX.Element;
+
+declare function SubmitForm(): React.JSX.Element;
+
+interface BoardTheme {
+    primary?: string;
+    /** A number is read as pixels, a string is used as-is (`"0.75rem"`). */
+    radius?: number | string;
+    surface?: string;
+    border?: string;
+    text?: string;
+    subtle?: string;
+    font?: string;
+}
+
+interface FewchursBoardProps {
+    tabs?: BoardTab[];
+    defaultTab?: BoardTab;
+    /** Shows this request above the list, for a link straight to one request. */
+    initialFeatureId?: string;
+    showDeclined?: boolean;
+    allowComments?: boolean;
+    emailField?: EmailFieldMode;
+    pageSize?: number;
+    labels?: Partial<BoardLabels>;
+    theme?: BoardTheme;
+    /** Drops every class name but keeps behaviour, ARIA and keyboard handling. */
+    unstyled?: boolean;
+    colorScheme?: "light" | "dark" | "system";
+    className?: string;
+    style?: CSSProperties;
+    /** Prefills the submit and follow forms. */
+    userEmail?: string;
+    isSubscriber?: boolean;
+    renderHeader?: () => ReactNode;
+    renderEmpty?: () => ReactNode;
+    renderFeature?: (feature: Feature, actions: FeatureActions) => ReactNode;
+    children?: ReactNode;
+}
+declare function BoardRoot({ tabs, defaultTab, initialFeatureId, showDeclined, allowComments, emailField, pageSize, labels, theme, unstyled, colorScheme, className, style, userEmail, isSubscriber, renderHeader, renderEmpty, renderFeature, children, }: FewchursBoardProps): React.JSX.Element;
+declare function BoardTabs(): React.JSX.Element | null;
+declare function SubmitTrigger(): React.JSX.Element;
+/** Level 1 by default, level 5 when given children to compose. */
+declare const FewchursBoard: typeof BoardRoot & {
+    Root: typeof BoardRoot;
+    Tabs: typeof BoardTabs;
+    List: typeof FeatureList;
+    SubmitTrigger: typeof SubmitTrigger;
+    SubmitForm: typeof SubmitForm;
+    Branding: typeof Branding;
+};
+
+interface FewchursBoardDialogProps extends FewchursBoardProps {
+    open: boolean;
+    onClose: () => void;
+    ariaLabel?: string;
+}
+declare function FewchursBoardDialog({ open, onClose, ariaLabel, ...boardProps }: FewchursBoardDialogProps): React.JSX.Element | null;
+
+declare function FeatureCard({ feature, defaultCommentsOpen, }: {
+    feature: Feature;
+    /** Opens the thread straight away, for a board linked to this one request. */
+    defaultCommentsOpen?: boolean;
+}): React.JSX.Element;
+
+interface VoteButtonProps {
+    feature: Feature;
+    isPending: boolean;
+    onToggle: () => void;
+}
+declare function VoteButton({ feature, isPending, onToggle }: VoteButtonProps): React.JSX.Element;
+
+declare function StatusBadge({ status }: {
+    status: FeatureStatus;
+}): React.JSX.Element | null;
+
+declare function CommentList({ featureId }: {
+    featureId: string;
+}): React.JSX.Element;
+declare function CommentForm({ featureId }: {
+    featureId: string;
+}): React.JSX.Element;
+
+declare function FollowForm({ feature }: {
+    feature: Feature;
+}): React.JSX.Element;
+
+interface UseFeaturesOptions {
+    sort?: FeatureSort;
+    status?: FeatureStatus[];
+    pageSize?: number;
+    enabled?: boolean;
+}
+interface UseFeaturesResult {
+    features: Feature[];
+    isLoading: boolean;
+    isLoadingMore: boolean;
+    error: FewchursError | null;
+    hasMore: boolean;
+    loadMore: () => Promise<void>;
+    refresh: () => Promise<void>;
+}
+declare function useFeatures({ sort, status, pageSize, enabled, }?: UseFeaturesOptions): UseFeaturesResult;
+
+interface UseFeatureOptions {
+    enabled?: boolean;
+}
+interface UseFeatureResult {
+    feature: Feature | null;
+    isLoading: boolean;
+    error: FewchursError | null;
+    refresh: () => Promise<void>;
+}
+/**
+ * One request by id, for a deep link into a board. The feature lands in the same store the
+ * lists use, so voting, commenting and following it behave exactly as they do in a list.
+ */
+declare function useFeature(featureId: string | undefined, { enabled }?: UseFeatureOptions): UseFeatureResult;
+
+interface UseCommentsOptions {
+    enabled?: boolean;
+}
+interface UseCommentsResult {
+    comments: Comment[];
+    isLoading: boolean;
+    isLoadingMore: boolean;
+    isSubmitting: boolean;
+    error: FewchursError | null;
+    submitError: FewchursError | null;
+    hasMore: boolean;
+    loadMore: () => Promise<void>;
+    add: (text: string, authorName?: string) => Promise<boolean>;
+}
+declare function useComments(featureId: string, { enabled }?: UseCommentsOptions): UseCommentsResult;
+
+interface UseVoteResult {
+    hasVoted: boolean;
+    upvoteCount: number;
+    isPending: boolean;
+    error: FewchursError | null;
+    toggle: () => Promise<void>;
+    vote: () => Promise<void>;
+    unvote: () => Promise<void>;
+}
+declare function useVote(featureId: string): UseVoteResult;
+
+interface UseSubmitFeatureResult {
+    submit: (input: SubmitFeatureInput) => Promise<Feature | null>;
+    isPending: boolean;
+    error: FewchursError | null;
+    reset: () => void;
+}
+declare function useSubmitFeature(): UseSubmitFeatureResult;
+
+interface UseFollowResult {
+    isFollowing: boolean;
+    isPending: boolean;
+    error: FewchursError | null;
+    follow: (email: string) => Promise<boolean>;
+    unfollow: () => Promise<boolean>;
+}
+declare function useFollow(featureId: string): UseFollowResult;
+
+interface UseFewchursConfigResult {
+    showBranding: boolean;
+    hideVoteCounts: boolean;
+    appName: string | null;
+    isLoading: boolean;
+}
+declare function useFewchursConfig(): UseFewchursConfigResult;
+
+declare const COOKIE_NAME = "fewchurs_did";
+declare function createDeviceId(): string;
+declare function readDeviceId(): string | null;
+/**
+ * Cookie first, storage second: a cookie is the only copy a same-origin server can read, so
+ * the board renders with the same identity on both sides and never mismatches on hydration.
+ */
+declare function resolveDeviceId(): string;
+
+declare function normalizeStatus(value: unknown): FeatureStatus;
+declare function normalizeFeature(value: unknown, deviceId: string | null): Feature;
+declare function normalizeComment(value: unknown, deviceId: string | null): Comment;
+declare function normalizeFeaturePage(value: unknown, deviceId: string | null): FeaturePage;
+declare function normalizeCommentPage(value: unknown, deviceId: string | null): CommentPage;
+declare function normalizeConfig(value: unknown): FewchursConfig;
+declare function normalizeVote(value: unknown): {
+    upvoteCount: number;
+    hasVoted: boolean;
+};
+
+declare function validateFeatureInput(input: SubmitFeatureInput): FewchursError | null;
+declare function validateCommentInput(input: CreateCommentInput): FewchursError | null;
+declare function validateEmail(email: string): FewchursError | null;
+
+export { type BoardContextValue, type BoardLabels, BoardRoot, type BoardTab, BoardTabs, type BoardTheme, Branding, type Comment, CommentForm, CommentList, type CommentPage, type CommentsState, type CreateCommentInput, DEFAULT_BASE_URL, DEFAULT_LABELS, DEFAULT_PAGE_SIZE, COOKIE_NAME as DEVICE_ID_COOKIE, type EmailFieldMode, type EventHandler, type Feature, type FeatureActions, FeatureCard, FeatureList, type FeaturePage, type FeatureSort, type FeatureStatus, type FetchLike, FewchursBoard, FewchursBoardDialog, type FewchursBoardDialogProps, type FewchursBoardProps, type FewchursClient, type FewchursClientOptions, type FewchursConfig, type FewchursContextValue, type FewchursError, type FewchursEvent, type FewchursEventName, FewchursProvider, type FewchursProviderProps, FollowForm, LIMITS, type ListCommentsParams, type ListFeaturesParams, type ListQuery, type ListState, type LoadStatus, ROADMAP_STATUSES, type Result, SDK_HEADER, SDK_VERSION, StatusBadge, type Store, type StoreOptions, type StoreState, type SubmitFeatureInput, SubmitForm, SubmitTrigger, type UseCommentsOptions, type UseCommentsResult, type UseFeatureOptions, type UseFeatureResult, type UseFeaturesOptions, type UseFeaturesResult, type UseFewchursConfigResult, type UseFollowResult, type UseSubmitFeatureResult, type UseVoteResult, VoteButton, commentsStateOf, createDeviceId, createFewchursClient, createStore, errorFromResponse, featureKey, listKey, listStateOf, mergeLabels, networkError, normalizeComment, normalizeCommentPage, normalizeConfig, normalizeFeature, normalizeFeaturePage, normalizeStatus, normalizeVote, readDeviceId, resolveDeviceId, useBoard, useComments, useFeature, useFeatures, useFewchurs, useFewchursConfig, useFollow, useSubmitFeature, useVote, userMessage, validateCommentInput, validateEmail, validateFeatureInput, validationError };