@simoncomputing/mui-bueno-v2 0.17.4 → 0.18.0

package/CHANGELOG.md

@@ -11,6 +11,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Minor increment --> singlular/minor changes. Minimal breaking changes.
 - Patch increment --> singlular/minor changes. Zero breaking changes.
 
+## [0.18.0] - 2025-09-22
+
+### Added
+
+- `TableColumn`
+    - Added `tableCellSx` styling `TableCell` in `Table` and/or `PaginatedTable`
+- `CitationManager`:
+    - Basic table offering CRUD operations for citations. Replaces `CitationMenu`.
+- `SelectableCitationManager`
+    - Condensed table offering CRUD operations for citations, including selecting citations. Intended to be used in modals/popups. Replaces `CitationMenu`.
+- `CitationField`, `CitationManager`, `SelectableCitationManager`:
+    - added `onDownloadAttachment` prop to support downloading attachments
+
+### Changed
+
+- `CitationField`, `CitationManager`, `SelectableCitationManager`:
+    - made `onDeleteCitation` prop optional
+
+### Removed
+
+- `CitationMenu`
+    - Replaced with `CitationManager` & `SelectableCitationManager`. See `Added` section.
+
+## [0.17.5] - 2025-09-22
+
+### Added
+
+- `CitationMenu`:
+    - added `renderAsSelectablePopup` prop
+
 ## [0.17.4] - 2025-09-16
 
 ### Changed

package/dist/@types/index.d.ts

@@ -113,6 +113,7 @@ export type EnvironmentInfo = {
  *      within the object. isMobile in case your styling depends on whether the user is viewing
  *      on a phone vs tablet/desktop
  * @property {string} sortName - (Optional) Passed instead of `fieldName` to onSortChange(fieldName, ...). Useful if you're rendering the same object in 2+ columns and need a way to differentiate when sorting.
+ * @property {SxProps<Theme>} tableCellSx - (Optional) styles applies to TableCell (non-mobile)
  */
 export type TableColumn<T, K extends keyof T> = {
     key?: string;
@@ -120,6 +121,7 @@ export type TableColumn<T, K extends keyof T> = {
     fieldName: K;
     render?: (value: T[K], object: T, isMobile: boolean) => React.ReactNode;
     sortName?: string;
+    tableCellSx?: SxProps<Theme>;
 };
 
 // Sort order for Tables

package/dist/components/Form/Inputs/CitationField/CitationBubbleMenuHandler.d.ts

@@ -1,5 +1,5 @@
 import { Extension } from '@tiptap/core';
-import { CitationBubbleMenuProps } from './CitationMenu/CitationBubbleMenu';
+import { CitationBubbleMenuProps } from './CitationManager/CitationBubbleMenu';
 declare module '@tiptap/core' {
     interface Commands<ReturnType> {
         citationBubbleMenu: {

package/dist/components/Form/Inputs/CitationField/CitationField.d.ts

@@ -60,13 +60,17 @@ export type CitationFieldProps = {
      *
      * Error handling is supported internally.
      */
-    onDeleteCitation: (id: number) => Promise<void>;
+    onDeleteCitation?: (id: number) => Promise<void>;
     /**
      * API call for retrieving a citation by id
      *
      * Error handling is supported internally.
      */
     getCitationById: (id: number) => Promise<Citation>;
+    /**
+     * API call to download the attachment
+     */
+    onDownloadAttachment?: (citation: Citation) => Promise<void>;
     /**
      * Error callback.
      *
@@ -78,9 +82,11 @@ export type CitationFieldProps = {
 /**
  * Rich Text field -- uses MUI Tip Tap
  *
- * Formik -- This field cannot be completely controlled, so keep in mind that the Formik value will not update until the field
- * __loses focus__. This is to prevent issues with converting from rich text to HTML as the user types as it could override
- * their changes unintentionally.
+ * IMPORTANT: As per Mui TipTap's documentation, it's not efficient to use it as a fully controlled component since the
+ * editor content has to be serialized to HTML (which is what is stored in Formik). Therefore, keep in mind that what is
+ * shown in the editor will not match the Formik value until the field __loses focus__.
+ *
+ * Recommended to use with `CitationFieldProvider` for cross-field synchronization.
  */
 export declare const CitationField: (props: CitationFieldProps) => import("react/jsx-runtime").JSX.Element;
 export default CitationField;

package/dist/components/Form/Inputs/CitationField/CitationFieldContext/CitationFieldContext.d.ts

@@ -1,9 +1,10 @@
 import { Citation } from '../../../../../@types';
 interface SyncContextType {
     citations: Citation[];
-    resync: () => void;
+    isLoaded: boolean;
     addUpdateCitation: (citation: Citation) => void;
     deleteCitation: (id: number) => void;
+    batchUpdate: (newCitations: Citation[]) => void;
 }
 export declare const SyncContext: import('react').Context<SyncContextType | undefined>;
 export declare const useCitationSync: () => SyncContextType;

package/dist/components/Form/Inputs/CitationField/CitationFieldContext/CitationFieldProvider.d.ts

@@ -4,5 +4,14 @@ type CitationFieldProviderProps = {
     children: React.ReactNode;
     getCitations: () => Promise<Citation[]>;
 };
+/**
+ * CitationFieldProvider ensures `CitationField` stays in sync with other `CitationField` components. Always
+ * use when multiple `CitationField` components are on the same page.
+ *
+ * NOTE: The provider is optimized to reduce excessive API calls. Currently, it will only perform the inital full
+ *       data fetch on initial load. Subsequent changes are updated locally based on what add/update/delete actions
+ *       are made by the user, but any remote additions/updates/deletions will not be fetched. Keep this in mind when
+ *       deciding what level to place the provider in your app so that you can control how often the provider is initialized.
+ */
 export declare const CitationFieldProvider: React.FC<CitationFieldProviderProps>;
 export {};

package/dist/components/Form/Inputs/CitationField/CitationManager/AttachmentForm.d.ts

@@ -0,0 +1,13 @@
+import { Citation, UnsavedAttachmentCitation } from '../../../../../@types';
+import { CitationManagerError } from './CitationAlert';
+export type AttachmentFormProps = {
+    id?: number;
+    title?: string;
+    onSave: (unsavedAttachment: UnsavedAttachmentCitation) => Promise<void>;
+    onCancel: () => void;
+    getCitationById: (id: number) => Promise<Citation>;
+    disableFileUpload?: boolean;
+    setError: React.Dispatch<React.SetStateAction<CitationManagerError | undefined>>;
+};
+declare const AttachmentForm: (props: AttachmentFormProps) => import("react/jsx-runtime").JSX.Element;
+export default AttachmentForm;

package/dist/components/Form/Inputs/CitationField/{CitationMenu/CitationMenu.d.ts → CitationManager/BaseCitationManager.d.ts}

@@ -1,5 +1,5 @@
 import { Citation, PageState, PageResponse, UnsavedCitation } from '../../../../../@types';
-export interface CitationMenuProps {
+export interface BaseCitationManagerProps {
     /**
      * API call for fetching citations. These will populate the "Insert Citation/Attachment(s)" table.
      */
@@ -15,11 +15,15 @@ export interface CitationMenuProps {
     /**
      * API call for deleting a citation/attachment.
      */
-    onDeleteCitation: (id: number) => Promise<void>;
+    onDeleteCitation?: (id: number) => Promise<void>;
     /**
      * API call for retrieving a citation by id
      */
     getCitationById: (id: number) => Promise<Citation>;
+    /**
+     * API call to download the attachment
+     */
+    onDownloadAttachment?: (citation: Citation) => Promise<void>;
     /**
      * Set which citations should be pre-checked in the citations table when this component is first rendered (used
      * to initialize useState).
@@ -40,7 +44,7 @@ export interface CitationMenuProps {
      *
      * Currently, this will be called when the data in the citations table changes, and when the content itself changes (ex. clicks on "Add Citation")
      */
-    onContentUpdate?: () => void;
+    onContentChange?: () => void;
     /**
      * Error callback.
      *
@@ -48,17 +52,13 @@ export interface CitationMenuProps {
      * help debug issues so developers can see specific details about an error.
      */
     onError?: (err: string) => void;
+    /**
+     * When true, the table will be rendered for pop-ups with the ability to select citations from the table.
+     * When false, teh table will be rendered as a basic paginated table with all columns displayed.
+     */
+    renderAsSelectablePopup?: boolean;
 }
-/**
- * Error for CitationMenu
- *   title = human-friendly/shortened version of the error (ex. "Failed to create citation")
- *   err = the actual error thrown by the exception that was caught
- */
-export type CitationMenuError = {
-    title: string;
-    err: string;
-};
-export declare enum CitationMenuState {
+export declare enum CitationManagerState {
     CITATIONS_TABLE = "Insert Citation/Attachment(s)",
     ADD_CITATION = "Add Citation",
     EDIT_CITATION = "Edit Citation",
@@ -66,9 +66,11 @@ export declare enum CitationMenuState {
     EDIT_ATTACHMENT = "Edit Attachment"
 }
 /**
- * CitationMenu handles creating, updating, and selecting citations.
+ * BaseCitationManager handles creating, updating, deleting, downloading and selecting citations.
+ *
+ * INTERNAL COMPONENT. Use wrapper instead: `SelectableCitationManager` or `CitationManager`
  *
- * Intended to be used within a bubble/pop-up/modal/dialog. For in-line citations, see CitationField instead.
+ * For in-line citations, see CitationField instead.
  */
-export declare function CitationMenu({ getCitationsPaginated, onCreateCitation, onUpdateCitation, onDeleteCitation, getCitationById, onSelectCitations, onCancel, initialSelectedIds, onContentUpdate, onError, }: CitationMenuProps): import("react/jsx-runtime").JSX.Element;
-export default CitationMenu;
+export declare function BaseCitationManager({ getCitationsPaginated, onCreateCitation, onUpdateCitation, onDeleteCitation, getCitationById, onDownloadAttachment, onSelectCitations, onCancel, initialSelectedIds, onContentChange, onError, renderAsSelectablePopup, }: BaseCitationManagerProps): import("react/jsx-runtime").JSX.Element;
+export default BaseCitationManager;

package/dist/components/Form/Inputs/CitationField/CitationManager/CitationAlert.d.ts

@@ -0,0 +1,17 @@
+type Props = {
+    error?: CitationManagerError;
+    setError: React.Dispatch<React.SetStateAction<CitationManagerError | undefined>>;
+    success?: string;
+    setSuccess: React.Dispatch<React.SetStateAction<string | undefined>>;
+};
+/**
+ * Error for BaseCitationManager, CitationManager & SelectableCitationManager
+ *   title = human-friendly/shortened version of the error (ex. "Failed to create citation")
+ *   err = the actual error thrown by the exception that was caught
+ */
+export type CitationManagerError = {
+    title: string;
+    err: string;
+};
+declare const CitationAlert: (props: Props) => import("react/jsx-runtime").JSX.Element;
+export default CitationAlert;

package/dist/components/Form/Inputs/CitationField/{CitationMenu → CitationManager}/CitationBubbleMenu.d.ts

@@ -1,11 +1,11 @@
 import { Except } from 'type-fest';
 import { ControlledBubbleMenuProps } from 'mui-tiptap';
-import { CitationMenuProps } from './CitationMenu';
-export type CitationBubbleMenuProps = Partial<Except<ControlledBubbleMenuProps, 'open' | 'editor' | 'children'>> & Omit<CitationMenuProps, 'onCancel' | 'onSelectCitations'> & {
+import { BaseCitationManagerProps } from './BaseCitationManager';
+export type CitationBubbleMenuProps = Partial<Except<ControlledBubbleMenuProps, 'open' | 'editor' | 'children'>> & Omit<BaseCitationManagerProps, 'onCancel' | 'onSelectCitations'> & {
     onChanged?: (ids: number[]) => void;
 };
 /**
- * TipTap Wrapper for CitationMenu so that it renders as a bubble/pop-up menu integrated
+ * TipTap Wrapper for SelectableCitationManager so that it renders as a bubble/pop-up menu integrated
  * with TipTap
  *
  * A component that renders a bubble menu when viewing, creating, or editing a
@@ -24,4 +24,4 @@ export type CitationBubbleMenuProps = Partial<Except<ControlledBubbleMenuProps,
  * update, which will happen if it's a child of the component using
  * `useEditor`).
  */
-export default function CitationBubbleMenuTipTap({ getCitationsPaginated, onCreateCitation, onUpdateCitation, onDeleteCitation, getCitationById, ...controlledBubbleMenuProps }: CitationBubbleMenuProps): import("react/jsx-runtime").JSX.Element | null;
+export default function CitationBubbleMenuTipTap({ getCitationsPaginated, onCreateCitation, onUpdateCitation, onDeleteCitation, getCitationById, onDownloadAttachment, ...controlledBubbleMenuProps }: CitationBubbleMenuProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/components/Form/Inputs/CitationField/{CitationMenu → CitationManager}/CitationForm.d.ts

@@ -1,11 +1,12 @@
 import { Citation, UnsavedUrlCitation } from '../../../../../@types';
-import { CitationMenuError } from './CitationMenu';
+import { CitationManagerError } from './CitationAlert';
 export type CitationFormProps = {
     id?: number;
+    title?: string;
     onSave: (unsavedUrl: UnsavedUrlCitation) => Promise<void>;
     onCancel: () => void;
     getCitationById: (id: number) => Promise<Citation>;
-    setError: React.Dispatch<React.SetStateAction<CitationMenuError | undefined>>;
+    setError: React.Dispatch<React.SetStateAction<CitationManagerError | undefined>>;
 };
 declare const CitationForm: (props: CitationFormProps) => import("react/jsx-runtime").JSX.Element;
 export default CitationForm;

package/dist/components/Form/Inputs/CitationField/CitationManager/CitationManager.d.ts

@@ -0,0 +1,7 @@
+import { BaseCitationManagerProps } from './BaseCitationManager';
+export type CitationManagerProps = Omit<BaseCitationManagerProps, 'initialSelectedIds' | 'onSelectCitations' | 'onCancel' | 'onContentChange' | 'renderAsSelectablePopup'>;
+/**
+ * CitationManager is a basic table that handles creating, updating, and deleting citations.
+ */
+export declare function CitationManager({ ...rest }: CitationManagerProps): import("react/jsx-runtime").JSX.Element;
+export default CitationManager;

package/dist/components/Form/Inputs/CitationField/{CitationMenu → CitationManager}/CitationTable.d.ts

@@ -1,12 +1,14 @@
 import { PageState, PageResponse, Citation } from '../../../../../@types';
-import { CitationMenuError } from './CitationMenu';
+import { CitationManagerError } from './CitationAlert';
 export type CitationTableProps = {
+    title: string;
     onCancel: () => void;
     onNewCitation: () => void;
     onNewAttachment: () => void;
     onEditCitation: (citation: Citation) => void;
     onEditAttachment: (citation: Citation) => void;
-    onDeleteCitation: (id: number) => Promise<void>;
+    onDeleteCitation?: (id: number) => Promise<void>;
+    onDownloadAttachment?: (citation: Citation) => Promise<void>;
     onSelect: (selectedIds: number[]) => void;
     getCitationsPaginated: (req: PageState) => Promise<PageResponse<Citation>>;
     selectedIds: number[];
@@ -18,7 +20,20 @@ export type CitationTableProps = {
      * help debug issues so developers can see specific details about an error.
      */
     onError?: (err: string) => void;
-    setError: React.Dispatch<React.SetStateAction<CitationMenuError | undefined>>;
+    setError: React.Dispatch<React.SetStateAction<CitationManagerError | undefined>>;
+    setSuccess: React.Dispatch<React.SetStateAction<string | undefined>>;
+    /**
+     * When true, the Source, Accessed At & Classification columns will not be displayed
+     * to preserve horizontal space.
+     */
+    condenseTable?: boolean;
+    /**
+     * When true, first column will be checkboxes, allowing users to select citations.
+     *
+     * Select/Cancel buttons will appear at the bottom of the component.
+     * NOTE: add buttons will move to the bottom of the component, inline with the Select/Cancel buttons.
+     */
+    canSelect?: boolean;
 };
 declare const CitationTable: (props: CitationTableProps) => import("react/jsx-runtime").JSX.Element;
 export default CitationTable;

package/dist/components/Form/Inputs/CitationField/CitationManager/SelectableCitationManager.d.ts

@@ -0,0 +1,9 @@
+import { BaseCitationManagerProps } from './BaseCitationManager';
+export type SelectableCitationManagerProps = Omit<BaseCitationManagerProps, 'renderAsSelectablePopup'>;
+/**
+ * SelectableCitationManager is a condensed table that handles creating, updating, deleting and selecting citations.
+ *
+ * It's intended to be used in a pop-up/modal.
+ */
+export declare function SelectableCitationManager({ ...rest }: SelectableCitationManagerProps): import("react/jsx-runtime").JSX.Element;
+export default SelectableCitationManager;