@valu/block-components 0.2.1 → 0.3.0

package/dist/components/document-picker/index.d.ts

@@ -0,0 +1,210 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+type DocumentPickerVariant = 'popover' | 'inline';
+/** Reason a picked document can't be displayed normally. */
+type MissingReason = 'deleted';
+/**
+ * A document item in the picker. `key` is a stable client-side uuid (use
+ * for React keys); `id` is the WordPress attachment id.
+ */
+interface DocumentItem {
+    key: string;
+    id: number;
+    title: string;
+    filename: string;
+    url: string;
+    mimeType: string;
+    /** Uppercase extension, e.g. `PDF`, `DOCX`. Empty string if unknown. */
+    extension: string;
+    /** File size in bytes (from `media_details.filesize` when available). */
+    fileSize?: number;
+    /** ISO-8601 date string of the last modification, when available. */
+    modified?: string;
+    /** Raw REST record so consumer filters can reach beyond the normalized shape. */
+    raw?: unknown;
+}
+/** A picked document resolved against the current entity store. */
+interface ResolvedDocumentItem extends DocumentItem {
+    missing?: MissingReason;
+}
+/** i18n bag — all optional, sensible defaults are used. */
+interface DocumentPickerLabels {
+    input?: string;
+    help?: string;
+    empty?: string;
+    loading?: string;
+    noDocumentsFound?: string;
+    selectedSingular?: string;
+    selectedPlural?: string;
+    limitReached?: string;
+    browseMediaLibrary?: string;
+    replace?: string;
+    remove?: string;
+    moveUp?: string;
+    moveDown?: string;
+    dragHandle?: string;
+    missing?: string;
+    openLink?: string;
+    extensionBadge?: string;
+}
+interface RequestContext {
+    query: string;
+    page: number;
+}
+interface FilterContext {
+    query: string;
+}
+interface SuggestionRenderState {
+    highlighted: boolean;
+    selected: boolean;
+}
+interface DocumentPickerProps {
+    /** Accessible name. Required. */
+    label: string;
+    /** Hide the label visually but keep it for screen readers. */
+    hideLabelFromVision?: boolean;
+    /** Help text shown under the input. */
+    help?: string;
+    /** Visual variant. @default 'popover' */
+    variant?: DocumentPickerVariant;
+    /** Controlled value. Omit for uncontrolled. */
+    value?: DocumentItem[];
+    /** Uncontrolled initial value. */
+    defaultValue?: DocumentItem[];
+    /** Called with the next array whenever the selection changes. */
+    onChange?: (items: DocumentItem[]) => void;
+    /** Maximum items the user can pick. `1` = single-select. @default Infinity */
+    maxItems?: number;
+    /** Allow drag-to-reorder. @default true when maxItems > 1 */
+    orderable?: boolean;
+    /** Input placeholder text. */
+    placeholder?: string;
+    /**
+     * MIME types to filter REST search and forward to the Media Library modal.
+     * @default DEFAULT_DOCUMENT_MIME_TYPES (PDF, Word, Excel, PowerPoint)
+     */
+    allowedMimeTypes?: string[];
+    /**
+     * Additional file extensions to accept (matched case-insensitively
+     * against the basename). Useful for documents with non-standard MIME.
+     */
+    allowedExtensions?: string[];
+    /** Items per page from the REST search endpoint. @default 10 (popover) / 20 (inline) */
+    perPage?: number;
+    /** Debounce between keystrokes and the search request, in ms. @default 250 */
+    inputDelayMs?: number;
+    /** In `popover` variant, fetch suggestions immediately when the popover opens. */
+    fetchOnOpen?: boolean;
+    /** Prevent duplicate items in the selection. @default true */
+    uniqueItems?: boolean;
+    /** Show the "Browse Media Library" button. @default true */
+    enableMediaLibrary?: boolean;
+    /** Show the uppercase extension badge on each row. @default true */
+    showExtensionBadge?: boolean;
+    /** Show file size on each row. @default true */
+    showFileSize?: boolean;
+    /** Show the upload/modified date on each row. @default false */
+    showModifiedDate?: boolean;
+    /** Final filter over normalized suggestions. */
+    filter?: (items: DocumentItem[], ctx: FilterContext) => DocumentItem[];
+    /** Rewrite the REST path before it is fetched. */
+    request?: (path: string, ctx: RequestContext) => string;
+    /** Custom suggestion-row renderer. */
+    renderSuggestion?: (item: DocumentItem, state: SuggestionRenderState) => ReactNode;
+    /** Custom selected-row renderer. */
+    renderSelected?: (item: ResolvedDocumentItem) => ReactNode;
+    /** i18n overrides. */
+    labels?: DocumentPickerLabels;
+    /** Extra class on the root element. */
+    className?: string;
+    /** Explicit id for the root element; used as prefix for ARIA ids. */
+    id?: string;
+}
+
+/**
+ * `<DocumentPicker />` — search for and attach WordPress document attachments
+ * (PDFs, Word, Excel, PowerPoint by default) to a block. Combines a fast
+ * REST-search popover/inline list with WordPress's native Media Library modal
+ * for browsing and uploading.
+ *
+ * The component is **controlled** when `value` is defined and **uncontrolled**
+ * (with optional `defaultValue`) otherwise. In both modes `onChange` fires
+ * with the full next array.
+ *
+ * @example
+ * <DocumentPicker
+ *     label="Downloadable documents"
+ *     value={attributes.documents}
+ *     onChange={(items) => setAttributes({ documents: items })}
+ * />
+ */
+declare const DocumentPicker: ({ label, hideLabelFromVision, help, variant, value: controlledValue, defaultValue, onChange, maxItems, orderable, placeholder, allowedMimeTypes, allowedExtensions, perPage, inputDelayMs, fetchOnOpen, uniqueItems, enableMediaLibrary, showExtensionBadge, showFileSize, showModifiedDate, filter, request, renderSuggestion, renderSelected, labels, className, id, }: DocumentPickerProps) => react_jsx_runtime.JSX.Element;
+
+interface MediaLibraryButtonProps {
+    allowedMimeTypes: string[];
+    allowedExtensions?: string[];
+    multiple: boolean;
+    value: DocumentItem[];
+    onSelect: (items: DocumentItem[]) => void;
+    labels: DocumentPickerLabels;
+    disabled?: boolean;
+    variant?: 'primary' | 'secondary' | 'tertiary';
+    label?: string;
+}
+declare const MediaLibraryButton: ({ allowedMimeTypes, allowedExtensions, multiple, value, onSelect, labels, disabled, variant, label, }: MediaLibraryButtonProps) => react_jsx_runtime.JSX.Element;
+
+interface ExtensionBadgeProps {
+    extension: string;
+    /** Override of the visible label (defaults to the uppercase extension). */
+    label?: string;
+}
+declare const ExtensionBadge: ({ extension, label }: ExtensionBadgeProps) => react_jsx_runtime.JSX.Element;
+
+interface FileSizeProps {
+    bytes: number | undefined;
+}
+declare const FileSize: ({ bytes }: FileSizeProps) => react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Default MIME types treated as "documents": PDF, Word, Excel, PowerPoint
+ * (both legacy and Office Open XML variants).
+ */
+declare const DEFAULT_DOCUMENT_MIME_TYPES: readonly string[];
+/** Extract the basename from a URL/path. Strips query and hash. */
+declare const basenameFromUrl: (url: string | undefined | null) => string;
+/** Uppercase extension from a URL or filename. `''` if none. */
+declare const extensionFromUrl: (url: string | undefined | null) => string;
+/**
+ * Human-readable file size. Mirrors the `wp_format_bytes()` style used in
+ * WP admin (1 KB = 1024 B). Returns an empty string when the input is
+ * undefined or non-positive.
+ */
+declare const formatFileSize: (bytes: number | undefined) => string;
+interface MediaRecordShape {
+    id: number;
+    title?: {
+        rendered?: string;
+    } | string;
+    source_url?: string;
+    url?: string;
+    mime_type?: string;
+    mime?: string;
+    media_details?: {
+        filesize?: number;
+        original_image?: string;
+    };
+    modified?: string;
+    modified_gmt?: string;
+    date?: string;
+    filename?: string;
+    link?: string;
+}
+/**
+ * Normalize a record from `/wp/v2/media` (or from `MediaUpload.onSelect`)
+ * into a `DocumentItem`. Tolerant of both shapes — `source_url`/`url`,
+ * `mime_type`/`mime`, etc.
+ */
+declare const mapMediaToDocumentItem: (raw: MediaRecordShape) => DocumentItem;
+
+export { DEFAULT_DOCUMENT_MIME_TYPES, type DocumentItem, DocumentPicker, type DocumentPickerLabels, type DocumentPickerProps, type DocumentPickerVariant, ExtensionBadge, FileSize, type FilterContext, MediaLibraryButton, type MissingReason, type RequestContext, type ResolvedDocumentItem, type SuggestionRenderState, basenameFromUrl, extensionFromUrl, formatFileSize, mapMediaToDocumentItem };