@crispy-seed/data-table 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import * as react from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
 
 declare interface DataTableVariant {
   /**
@@ -66,6 +67,50 @@ interface ToolbarFilter {
  */
 type DataTableCalcOp = "count" | "countFilled" | "sum" | "average" | "min" | "max";
 
+/** Everything a saved view actually captures -- deliberately the same five controlled
+ *  props `useDataTableColumns` + the toolbar sort/filter hooks already expose, so
+ *  "restore this view" is just handing each field back to its own `on*Change` setter,
+ *  not a bespoke apply-state routine this file would have to keep in sync with them by
+ *  hand. Every field is optional: a consumer capturing only PART of the table's state
+ *  (e.g. column layout but not filters) still produces a valid view. */
+interface DataTableViewState {
+    columnOrder?: string[];
+    hiddenColumnKeys?: string[];
+    columnWidths?: Record<string, number>;
+    pinnedColumnKeys?: string[];
+    toolbarSorts?: ToolbarSort[];
+    toolbarFilters?: ToolbarFilter[];
+}
+/** One named, saved view. */
+interface DataTableView {
+    id: string;
+    name: string;
+    state: DataTableViewState;
+}
+
+interface UseDataTableViewsProps {
+    /** 제어할 저장된 view 목록입니다. */
+    views?: DataTableView[];
+    /** 비제어 방식으로 사용할 때의 초기 view 목록입니다. */
+    defaultViews?: DataTableView[];
+    /** view 목록이 바뀔 때(생성/이름변경/삭제) 호출됩니다. */
+    onViewsChange?: (views: DataTableView[]) => void;
+    /** 제어할, 현재 활성화된 view의 id입니다 (`null`은 "저장된 view 없음"). */
+    activeViewId?: string | null;
+    /** 비제어 방식으로 사용할 때의 초기 활성 view id입니다. */
+    defaultActiveViewId?: string | null;
+    /** 활성 view가 바뀔 때 호출됩니다. */
+    onActiveViewIdChange?: (id: string | null) => void;
+    /**
+     * 기본 localStorage 저장소의 key입니다. 이 hook이 `views`를 실제로 소유할 때만
+     * (즉 `views`가 제어되지 않을 때만) 마운트 시 한 번 읽고, 바뀔 때마다 다시
+     *씁니다 -- `views`를 직접 제어하는 소비자(예: 나중에 서버에 저장하는 tether)는
+     * 자기 자신의 저장소를 이미 갖고 있으므로 이 hook이 localStorage에 그림자
+     * 복사본을 만들 이유가 없습니다. 생략하면 영속화 없이 메모리에만 남습니다.
+     */
+    storageKey?: string;
+}
+
 type DataTableCellType = "text" | "entity" | "url" | "email" | "tags" | "status" | "number" | "currency" | "date" | "datetime" | "rating" | "checkbox";
 
 /** A `select`/`reference`/`actor` editor's own choice list -- `value`/`label` are
@@ -211,6 +256,16 @@ interface DataTableColumn<TRow> {
      * 옵션의 문자열 그 자체입니다). 생략하면 `value`(또는 `row[key]`)를 그대로 씁니다.
      */
     editValue?: (row: TRow) => string | number | boolean;
+    /**
+     * `type: "entity"` 열에서만 쓰입니다 (your-moon/crisp#601 이식). 행에 마우스를
+     * 올리거나 키보드 포커스를 받으면 셀 오른쪽 끝에 "미리보기 열기" 아이콘이
+     * 나타납니다 -- crisp가 측정한 것과 동일한 20px 고스트 버튼(`radius.sm`,
+     * 평상시 muted, hover에서 진해짐). 생략하면 아이콘이 렌더링되지 않습니다
+     * (기본값). `type`이 다르면 무시됩니다.
+     */
+    onOpenPreview?: (row: TRow) => void;
+    /** `onOpenPreview` 아이콘의 aria-label입니다. @default "Open preview" */
+    openPreviewLabel?: string;
 }
 interface DataTableProps<TRow extends {
     id: string;
@@ -330,6 +385,14 @@ interface DataTableProps<TRow extends {
     defaultColumnLabels?: Record<string, string>;
     /** 열 이름이 바뀔 때 호출됩니다. */
     onColumnLabelsChange?: (labels: Record<string, string>) => void;
+    /** 제어할, 왼쪽에 고정(pin)된 열의 key 목록입니다 (Attio의 컬럼 메뉴 "Pin column").
+     *  선택 열과 `actions: true` 열은 이미 자기만의 고정 메커니즘(`stickyFirst`/
+     *  자동 `stickyLast`)을 갖고 있으므로 이 목록에 넣지 않아도 됩니다. */
+    pinnedColumnKeys?: string[];
+    /** 비제어 방식으로 사용할 때의 초기 고정 열 목록입니다. */
+    defaultPinnedColumnKeys?: string[];
+    /** 고정 열 목록이 바뀔 때(핀/언핀) 호출됩니다. */
+    onPinnedColumnKeysChange?: (pinned: string[]) => void;
     /** 순서/숨김/이름 중 무엇이든 바뀌어 "실제로 보여줄 열 목록"이 달라질 때마다,
      *  그 결과(순서·숨김·이름이 반영된 `columns`)를 통째로 받는 편의 콜백입니다 --
      *  위 세 쌍의 콜백을 각각 다루는 대신 한 곳에서 "지금 보이는 열 구성"을 저장하고
@@ -411,5 +474,256 @@ declare const DataTable: <TRow extends {
     ref?: react.ForwardedRef<HTMLDivElement>;
 }) => react.ReactElement;
 
-export { DataTable };
-export type { DataTableColumn, DataTableColumnKind, DataTableProps, ToolbarFilter, ToolbarFilterOp, ToolbarSort, ToolbarSortDirection };
+interface DataTableViewsControlProps extends UseDataTableViewsProps {
+    /** The trigger's label when no view is active. @default "Views" */
+    label?: string;
+    /** Renders an extra leading row in the popover that clears the active view (back to
+     *  `label`'s own unfiltered state) -- omit (the default) when a consumer has no
+     *  meaningful "no view" state to switch back to. */
+    showClearRow?: boolean;
+    /** The clear row's own label, when `showClearRow` is on. @default "label" */
+    clearLabel?: react.ReactNode;
+    /**
+     * Reads the table's CURRENT column order/visibility/widths/pins + toolbar sort/
+     * filter conditions -- called when the user picks "Save as new view" or "Update
+     * view". Build this from the same controlled state you pass to `<DataTable
+     * columnOrder=... toolbarSorts=... />` (or, uncontrolled, from `onColumnsChange`/
+     * `onToolbarSortsChange`/... mirrored into your own state).
+     */
+    captureState: () => DataTableViewState;
+    /** Applies a selected view's saved state back onto the table -- typically each of
+     *  your own `setColumnOrder`/`setHiddenColumnKeys`/`setColumnWidths`/
+     *  `setPinnedColumnKeys`/`setToolbarSorts`/`setToolbarFilters` setters, one per
+     *  field present on `state` (every field is optional -- a view that only captured
+     *  column layout should leave sort/filter alone). */
+    applyState: (state: DataTableViewState) => void;
+    newViewLabel?: string;
+    updateViewLabel?: string;
+    renameLabel?: string;
+    deleteLabel?: string;
+    /** aria-label for the rename text input, given the view's own name. */
+    renameInputLabel?: (name: string) => string;
+}
+/**
+ * A compact saved-views switcher -- current view name (or `label`) as the trigger,
+ * a popover listing every saved view (click to switch, inline Rename/Delete), a
+ * trailing "Save as new view", and (once a view is active) "Update view" to overwrite
+ * the loaded view with the table's current state.
+ */
+declare function DataTableViewsControl({ label, showClearRow, clearLabel, captureState, applyState, newViewLabel, updateViewLabel, renameLabel, deleteLabel, renameInputLabel, ...viewsProps }: DataTableViewsControlProps): react_jsx_runtime.JSX.Element;
+declare namespace DataTableViewsControl {
+    var displayName: string;
+}
+
+type ResizablePanelSide = "left" | "right";
+
+type ResizablePanelHandleVariant = "panel" | "column";
+type ResizablePanelProps = Omit<react.ComponentPropsWithoutRef<"div">, "children" | "onResize"> & {
+    /** Which edge of its container the panel is anchored to. @default "left" */
+    side?: ResizablePanelSide;
+    /** Controlled width, in px. */
+    width?: number;
+    /** Initial width, in px, when uncontrolled. @default 280 */
+    defaultSize?: number;
+    /** Fires with the next width on every drag move, and once more with the
+     *  final, CSS-clamped width once a drag ends. */
+    onWidthChange?: (width: number) => void;
+    /** `min-width` in px. @default 200 */
+    min?: number;
+    /**
+     * `max-width` -- a px number, or a raw CSS expression for callers that
+     * need a real clamp, e.g. `max="min(60%, 100% - 350px)"`. Constraints are
+     * never re-applied in JS: the handler writes the unclamped drag width, and
+     * the browser's own `min-width`/`max-width` resolve the rendered size.
+     */
+    max?: number | string;
+    /**
+     * Layout model: "docked" (default) reserves flow width and sits in-line
+     * with a hairline border; "floating" takes the panel out of flow
+     * (`position: fixed`, an 8px gutter, r10, the measured floating shadow).
+     */
+    floating?: boolean;
+    /** Resize-handle geometry -- "panel" (default) or "column" (table edges). */
+    handleVariant?: ResizablePanelHandleVariant;
+    /**
+     * Renders the drag handle. `false` gives a fixed-width, non-interactive
+     * panel (e.g. `RecordPanel`'s own `resizable={false}` default) -- not part
+     * of crisp's own API, added here so a consumer built ON this primitive
+     * (like `RecordPanel`) can opt out of dragging entirely without crisp's
+     * duplicate resize-handle implementation. @default true
+     */
+    resizable?: boolean;
+    /**
+     * Persist width as a percentage of the container under this key (a `%`,
+     * not px, so the panel keeps its proportion on resize). Only applies when
+     * `width` is uncontrolled.
+     */
+    storageKey?: string;
+    className?: string;
+    children?: react.ReactNode;
+};
+/**
+ * An adjustable-panel primitive: a spacer that reserves layout width plus a
+ * panel that overlays it, so the panel can move between docked (in-flow) and
+ * floating (`position: fixed`, an overlay) without a reflow glitch. Drag the
+ * edge handle to resize; constraints are CSS `min-width`/`max-width`, never
+ * re-clamped in JS. Ported from your-moon/crisp's `ResizablePanel`
+ * (`components/resizablepanel/`); state/drag behavior lives in
+ * `useResizablePanel` (`@seed-design/react-resizable-panel`), this component
+ * owns the DOM + recipe classes on top of it.
+ */
+declare const ResizablePanel: react.ForwardRefExoticComponent<Omit<Omit<react.DetailedHTMLProps<react.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "children" | "onResize"> & {
+    /** Which edge of its container the panel is anchored to. @default "left" */
+    side?: ResizablePanelSide;
+    /** Controlled width, in px. */
+    width?: number;
+    /** Initial width, in px, when uncontrolled. @default 280 */
+    defaultSize?: number;
+    /** Fires with the next width on every drag move, and once more with the
+     *  final, CSS-clamped width once a drag ends. */
+    onWidthChange?: (width: number) => void;
+    /** `min-width` in px. @default 200 */
+    min?: number;
+    /**
+     * `max-width` -- a px number, or a raw CSS expression for callers that
+     * need a real clamp, e.g. `max="min(60%, 100% - 350px)"`. Constraints are
+     * never re-applied in JS: the handler writes the unclamped drag width, and
+     * the browser's own `min-width`/`max-width` resolve the rendered size.
+     */
+    max?: number | string;
+    /**
+     * Layout model: "docked" (default) reserves flow width and sits in-line
+     * with a hairline border; "floating" takes the panel out of flow
+     * (`position: fixed`, an 8px gutter, r10, the measured floating shadow).
+     */
+    floating?: boolean;
+    /** Resize-handle geometry -- "panel" (default) or "column" (table edges). */
+    handleVariant?: ResizablePanelHandleVariant;
+    /**
+     * Renders the drag handle. `false` gives a fixed-width, non-interactive
+     * panel (e.g. `RecordPanel`'s own `resizable={false}` default) -- not part
+     * of crisp's own API, added here so a consumer built ON this primitive
+     * (like `RecordPanel`) can opt out of dragging entirely without crisp's
+     * duplicate resize-handle implementation. @default true
+     */
+    resizable?: boolean;
+    /**
+     * Persist width as a percentage of the container under this key (a `%`,
+     * not px, so the panel keeps its proportion on resize). Only applies when
+     * `width` is uncontrolled.
+     */
+    storageKey?: string;
+    className?: string;
+    children?: react.ReactNode;
+} & react.RefAttributes<HTMLDivElement>>;
+
+/** One Highlights card -- label, value and an optional icon, laid out the way
+ *  Attio's own peek panel lays its own out (your-moon/crisp#448, measured
+ *  live): a 2-column grid, no card chrome, a muted label row with a
+ *  trailing icon, a filled-colour value below it. */
+type RecordPanelHighlight = {
+    key: string;
+    label: string;
+    value: react.ReactNode;
+    icon?: react.ComponentType<{
+        size?: number;
+    }>;
+};
+/** One collapsed section below Activity (your-moon/crisp#413) -- Attio's own
+ *  peek shows Emails/Notes/Tasks this way, each a label + a count, expanding
+ *  into the consumer's own content when clicked. Omitting `content` renders
+ *  the row but not as a button, matching the live DOM measured on an empty
+ *  section: no chevron, no click handler, nothing to expand into yet. */
+type RecordPanelSection = {
+    key: string;
+    label: string;
+    count: number;
+    content?: react.ReactNode;
+};
+/** The record this panel previews. Only `name` is read directly here --
+ *  everything else the panel shows comes from `highlights`/`activity`/
+ *  `sections`, the consumer's own data. Unlike crisp's own `RecordPanel`
+ *  (which reads `Row` from `product/recordpage/column`), this port has no
+ *  such type to depend on -- crispy-seed has no RecordPage -- so this stays
+ *  a minimal, consumer-extendable shape. */
+type RecordPanelRecord = {
+    name?: string;
+    [key: string]: unknown;
+};
+type RecordPanelProps = Omit<react.ComponentPropsWithoutRef<"div">, "children" | "title" | "onResize"> & {
+    /** Whether the panel is mounted/visible. */
+    open: boolean;
+    onClose: () => void;
+    /** Label for the close control. */
+    closeLabel?: string;
+    /**
+     * A toolbar row above the panel's own identity header (your-moon/crisp#601,
+     * measured live on app.attio.com's peek): Close, then Previous/Next on the
+     * left, an "Open record" icon on the right. Close always renders
+     * (`onClose` is required); Previous/Next/Open record each render only when
+     * given a handler.
+     */
+    onOpenRecord?: () => void;
+    openRecordLabel?: string;
+    onPrevious?: () => void;
+    previousRecordLabel?: string;
+    onNext?: () => void;
+    nextRecordLabel?: string;
+    /** "2 of 37 in All Companies" (your-moon/crisp#413) -- a single
+     *  pre-formatted string; omit for no counter at all. */
+    counterLabel?: react.ReactNode;
+    /**
+     * Lets a person drag the panel wider or narrower from its own left edge --
+     * this port reuses `ResizablePanel`'s own handle (`side="right"`, whose
+     * handle sits at the panel's inline-start/left edge, the same physical
+     * position crisp's own hand-rolled resize strip measured). Uncontrolled by
+     * default; pass `width`/`onWidthChange` together to own it instead.
+     * @default false
+     */
+    resizable?: boolean;
+    width?: number;
+    defaultWidth?: number;
+    onWidthChange?: (width: number) => void;
+    minWidth?: number;
+    maxWidth?: number;
+    /** The panel's heading, and so its accessible name. Defaults to `record.name`. */
+    title?: react.ReactNode;
+    /** Avatar image URL beside the title. Omit for an initials tile built from
+     *  `record.name`'s first character. */
+    avatar?: string;
+    /** The record to show; renders nothing when `open` is false or `record`
+     *  is null. */
+    record: RecordPanelRecord | null;
+    /** Heading above the highlight cards (default "Highlights"). Omit the
+     *  whole section by omitting `highlights`. */
+    highlightsLabel?: react.ReactNode;
+    highlights?: RecordPanelHighlight[];
+    /** Heading above the activity feed (default "Activity"). */
+    activityLabel?: react.ReactNode;
+    viewAllActivityLabel?: react.ReactNode;
+    onViewAllActivity?: () => void;
+    activity?: react.ReactNode;
+    /** Collapsed sections below Activity (your-moon/crisp#413). Omit for no
+     *  sections at all. */
+    sections?: RecordPanelSection[];
+    /** Rendered below the panel's content, e.g. an Edit button. */
+    footer?: react.ReactNode;
+    className?: string;
+};
+/**
+ * Right-side record peek panel -- Attio's own peek shows a Highlights card
+ * area and an Activity feed (measured live). Ported from your-moon/crisp's
+ * `RecordPanel` (`product/recordpanel/`), built ON `ResizablePanel`
+ * (`side="right" floating`) rather than crisp's own duplicate absolute-
+ * positioning/slide-in/resize-handle implementation -- the outer shell (the
+ * `@starting-style` slide-in, the floating elevation, the drag handle
+ * itself) all come from that primitive; this component only renders the
+ * CONTENT inside it.
+ */
+declare function RecordPanel({ open, record, onClose, className, closeLabel, onOpenRecord, openRecordLabel, onPrevious, previousRecordLabel, onNext, nextRecordLabel, title, avatar, highlightsLabel, highlights, counterLabel, resizable, width, defaultWidth, onWidthChange, minWidth, maxWidth, activityLabel, viewAllActivityLabel, onViewAllActivity, activity, sections, footer, ...rest }: RecordPanelProps): react_jsx_runtime.JSX.Element | null;
+declare namespace RecordPanel {
+    var displayName: string;
+}
+
+export { DataTable, DataTableViewsControl, RecordPanel, ResizablePanel };
+export type { DataTableColumn, DataTableColumnKind, DataTableProps, DataTableView, DataTableViewState, DataTableViewsControlProps, RecordPanelHighlight, RecordPanelProps, RecordPanelRecord, RecordPanelSection, ResizablePanelHandleVariant, ResizablePanelProps, ResizablePanelSide, ToolbarFilter, ToolbarFilterOp, ToolbarSort, ToolbarSortDirection };