@instantdb/components 0.0.1

package/src/components/explorer/expandable-deleted-attr.tsx

@@ -0,0 +1,170 @@
+import {
+  ArrowUturnLeftIcon,
+  ChevronDownIcon,
+  ChevronRightIcon,
+} from '@heroicons/react/24/outline';
+import { Button } from '@lib/components/ui';
+import {
+  DBAttr,
+  relationshipConstraintsInverse,
+  RelationshipKinds,
+} from '@lib/types';
+import { add, formatDistanceToNow } from 'date-fns';
+import React, { ReactNode } from 'react';
+
+type SoftDeletedAttr = DBAttr & {
+  'deletion-marked-at': string;
+};
+
+interface ExpandableDeletedAttrProps {
+  attr: SoftDeletedAttr;
+  gracePeriodDays: number;
+  onRestore: (attrId: string) => void;
+  isExpanded: boolean;
+  setIsExpanded: (state: boolean) => void;
+}
+
+export const ExpandableDeletedAttr: React.FC<ExpandableDeletedAttrProps> = ({
+  attr,
+  gracePeriodDays,
+  isExpanded,
+  setIsExpanded,
+  onRestore,
+}) => {
+  const date = add(new Date(attr['deletion-marked-at']), {
+    days: gracePeriodDays,
+  });
+
+  const getForwardLabel = () => {
+    return attr['forward-identity'][2];
+  };
+
+  const getReverseLabel = () => {
+    return attr['reverse-identity']?.[2];
+  };
+
+  const getEtypes = () => {
+    const forwardEtype = attr['forward-identity'][1];
+    const reverseEtype = attr['reverse-identity']?.[1];
+    return { forwardEtype: forwardEtype, reverseEtype };
+  };
+
+  const getRelationshipType = (): RelationshipKinds => {
+    const key = `${attr.cardinality}-${attr['unique?']}`;
+    return relationshipConstraintsInverse[key];
+  };
+
+  const toggleExpanded = () => {
+    setIsExpanded(!isExpanded);
+  };
+
+  const relationshipInfo = ((): Array<{ label: string; value: ReactNode }> => {
+    if (attr['value-type'] === 'blob') {
+      return [];
+    }
+
+    const relationshipType = getRelationshipType();
+    const { forwardEtype: forwardEtype, reverseEtype: reverseEtype } =
+      getEtypes();
+    const forwardLabel = getForwardLabel();
+    const reverseLabel = getReverseLabel();
+
+    const getCardinalityText = (
+      relType: RelationshipKinds,
+      isForward: boolean,
+    ) => {
+      if (relType === 'one-one') return 'has one';
+      if (relType === 'many-many') return 'has many';
+      if (relType === 'one-many') return isForward ? 'has one' : 'has many';
+      if (relType === 'many-one') return isForward ? 'has many' : 'has one';
+      return 'has';
+    };
+
+    return [
+      {
+        label: 'forward',
+        value: (
+          <span>
+            <strong>{forwardEtype}</strong>{' '}
+            {getCardinalityText(relationshipType, true)}{' '}
+            <strong>{forwardLabel}</strong>
+          </span>
+        ),
+      },
+      {
+        label: 'reverse',
+        value: (
+          <span>
+            <strong>{reverseEtype}</strong>{' '}
+            {getCardinalityText(relationshipType, false)}{' '}
+            <strong>{reverseLabel}</strong>
+          </span>
+        ),
+      },
+    ];
+  })();
+
+  const tableRows: Array<{ label: string; value: ReactNode }> = [
+    { label: 'type', value: attr['value-type'] },
+    ...relationshipInfo,
+  ];
+
+  return (
+    <div>
+      <div
+        className="flex cursor-pointer items-center justify-between"
+        onClick={toggleExpanded}
+      >
+        <div className="flex items-center gap-3">
+          {isExpanded ? (
+            <ChevronDownIcon width={14} className="text-gray-400" />
+          ) : (
+            <ChevronRightIcon width={14} className="text-gray-400" />
+          )}
+          <span className="font-mono text-sm font-medium">
+            {attr['forward-identity'][2]}
+          </span>
+          <span className="font-mono text-xs text-gray-400">
+            expires {formatDistanceToNow(date, { includeSeconds: false })}
+          </span>
+        </div>
+        <Button
+          className="px-1"
+          size="mini"
+          variant="subtle"
+          onClick={(e) => {
+            e.stopPropagation();
+            onRestore(attr.id);
+          }}
+        >
+          <ArrowUturnLeftIcon width={14} />
+          Restore
+        </Button>
+      </div>
+
+      {isExpanded && (
+        <div className="pb-3 pl-6">
+          <table className="mt-2 w-full text-left font-mono text-xs text-gray-500">
+            <tbody>
+              {tableRows.map((row, index) => (
+                <tr
+                  key={row.label}
+                  className={
+                    index === tableRows.length - 1
+                      ? 'pl-2'
+                      : 'border-b border-gray-200'
+                  }
+                >
+                  <td className="py-1 pr-4 pl-2 font-medium text-gray-700">
+                    {row.label}
+                  </td>
+                  <td className="py-1 text-gray-600">{row.value}</td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      )}
+    </div>
+  );
+};

package/src/components/explorer/explorer-layout.tsx

@@ -0,0 +1,156 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { useExplorerProps } from '.';
+import { SchemaNamespace } from '@lib/types';
+import { Button, cn, Dialog, ToggleCollection, useDialog } from '../ui';
+import {
+  RecentlyDeletedNamespaces,
+  useRecentlyDeletedNamespaces,
+} from './recently-deleted';
+import { useStableDB } from '@lib/hooks/useStableDB';
+import {
+  Bars3Icon,
+  ChevronLeftIcon,
+  PlusIcon,
+} from '@heroicons/react/24/solid';
+import { NewNamespaceDialog } from './new-namespace-dialog';
+import { InnerExplorer } from './inner-explorer';
+import { useClickOutside } from '@lib/hooks/useClickOutside';
+
+// Holds the explorer table itself and also the sidebar to select / create namespaces
+export const ExplorerLayout = ({
+  namespaces,
+  db,
+}: {
+  namespaces: SchemaNamespace[];
+  db: ReturnType<typeof useStableDB>;
+}) => {
+  const props = useExplorerProps();
+
+  const recentlyDeletedNsDialog = useDialog();
+  const newNsDialog = useDialog();
+
+  const selectedNamespace = namespaces.find(
+    (ns) => ns.id === props.explorerState?.namespace,
+  );
+  const [isNsOpen, setIsNsOpen] = useState(false);
+  const nsRef = useRef<HTMLDivElement>(null);
+
+  useClickOutside(nsRef, () => {
+    setIsNsOpen(false);
+  });
+
+  // Auto-select first namespace if none selected
+  useEffect(() => {
+    if (!selectedNamespace && namespaces.length > 0) {
+      props.setExplorerState({ namespace: namespaces[0].id });
+    }
+  }, [selectedNamespace, namespaces, props]);
+
+  const deletedNamespaces = useRecentlyDeletedNamespaces(props.appId);
+
+  return (
+    <div
+      className={cn(
+        'relative flex w-full flex-1 overflow-hidden border-solid dark:bg-neutral-800',
+        props.className,
+      )}
+    >
+      <Dialog {...recentlyDeletedNsDialog}>
+        <RecentlyDeletedNamespaces appId={props.appId} db={db} />
+      </Dialog>
+      <Dialog {...newNsDialog}>
+        <NewNamespaceDialog
+          db={db}
+          onClose={(p) => {
+            newNsDialog.onClose();
+
+            if (p?.name) {
+              props.setExplorerState({ namespace: p.name });
+            }
+          }}
+        />
+      </Dialog>
+
+      <div
+        ref={nsRef}
+        className={cn(
+          'absolute top-0 bottom-0 left-0 z-40 flex min-w-[200px] flex-col gap-1 border-r border-solid border-r-gray-200 bg-white p-2 shadow-md md:static md:flex md:shadow-none dark:border-neutral-700 dark:bg-neutral-800 dark:text-white',
+          {
+            hidden: !isNsOpen,
+          },
+        )}
+      >
+        <div className="flex items-center gap-1 text-sm font-semibold dark:text-white">
+          <ChevronLeftIcon
+            height="1rem"
+            className="cursor-pointer md:hidden dark:text-white"
+            onClick={() => setIsNsOpen(false)}
+          />
+          Namespaces
+        </div>
+        <div className="flex flex-col gap-2 border-r border-gray-300 bg-neutral-100 p-1 md:hidden dark:border-neutral-700 dark:bg-neutral-800">
+          <button
+            className="flex cursor-pointer items-center gap-1 rounded-sm px-1 py-0.5 select-none hover:bg-neutral-300 dark:hover:bg-neutral-700"
+            onClick={(e) => {
+              e.stopPropagation();
+              setIsNsOpen(true);
+            }}
+          >
+            <Bars3Icon height="1rem" className="dark:text-white" />
+          </button>
+        </div>
+        {namespaces ? (
+          <>
+            <div className="overflow-x-hidden overflow-y-auto">
+              {namespaces.length ? (
+                <ToggleCollection
+                  className="text-sm"
+                  selectedId={props.explorerState?.namespace}
+                  items={namespaces.map((ns) => ({
+                    id: ns.id,
+                    label: ns.name,
+                  }))}
+                  onChange={(ns) => {
+                    props.setExplorerState({ namespace: ns.id });
+                  }}
+                />
+              ) : null}
+            </div>
+            <Button
+              variant="secondary"
+              size="mini"
+              className="justify-center"
+              onClick={newNsDialog.onOpen}
+            >
+              <PlusIcon height="1rem" /> Create
+            </Button>
+            {deletedNamespaces.length ? (
+              <Button
+                className="justify-start gap-2 rounded-sm p-2"
+                variant="subtle"
+                size="nano"
+                onClick={recentlyDeletedNsDialog.onOpen}
+              >
+                <span className="rounded-sm bg-gray-200 px-1">
+                  {deletedNamespaces.length}
+                </span>
+                <span>Recently Deleted</span>
+              </Button>
+            ) : null}
+          </>
+        ) : (
+          <div className="animate-slow-pulse flex w-full flex-col gap-2">
+            {Array.from({ length: 3 }).map((_, i) => (
+              <div
+                key={i}
+                className="h-4 w-full rounded-md bg-neutral-300 dark:bg-neutral-700"
+              ></div>
+            ))}
+          </div>
+        )}
+      </div>
+
+      {props.explorerState && <InnerExplorer namespaces={namespaces} db={db} />}
+    </div>
+  );
+};

package/src/components/explorer/index.tsx

@@ -0,0 +1,217 @@
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+
+import { StyleMe } from '@lib/components/StyleMe';
+import type { HasDefault, WithDefaults, WithOptional } from '@lib/types';
+import { config } from '@lib/config';
+import { ExplorerLayout } from './explorer-layout';
+import { useSchemaQuery } from '@lib/hooks/explorer';
+import { useStableDB } from '@lib/hooks/useStableDB';
+import ErrorBoundary from '@lib/components/error-boundary';
+
+interface ExplorerProps {
+  appId: string;
+  adminToken: string;
+  apiURI: HasDefault<string>;
+  websocketURI: HasDefault<string>;
+  darkMode: HasDefault<boolean>;
+
+  className?: string;
+
+  // state management
+  // When undefined: uncontrolled mode (component manages its own state)
+  // When null: controlled mode with no selection
+  // When ExplorerNav: controlled mode with a selection
+  explorerState: HasDefault<ExplorerNav | null | undefined>;
+  setExplorerState: HasDefault<
+    React.Dispatch<React.SetStateAction<ExplorerNav | null>>
+  >;
+  useShadowDOM: HasDefault<boolean>;
+}
+
+const ExplorerPropsContext = createContext<{
+  props: WithDefaults<ExplorerProps> | null;
+  history: {
+    push: (
+      filter: React.SetStateAction<ExplorerNav>,
+      replace?: boolean,
+    ) => void;
+    pop: () => void;
+    items: ExplorerNav[];
+  };
+}>({ props: null, history: { push: () => {}, pop: () => {}, items: [] } });
+
+export const useExplorerProps = (): WithDefaults<ExplorerProps> => {
+  const ctx = useContext(ExplorerPropsContext);
+  if (!ctx.props) {
+    throw new Error(
+      'useExplorerProps must be used within an Explorer component',
+    );
+  }
+  return ctx.props;
+};
+
+export const useExplorerState = () => {
+  const ctx = useContext(ExplorerPropsContext);
+  if (!ctx.props || !ctx.props.explorerState) {
+    throw new Error(
+      'useExplorerProps must be used within an Explorer component',
+    );
+  }
+  return { explorerState: ctx.props.explorerState, history: ctx.history };
+};
+
+const isControlled = (props: WithOptional<ExplorerProps>): boolean => {
+  // Component is controlled if explorerState prop is explicitly provided
+  // (even if null - that means "no selection" in controlled mode)
+  return (
+    props.explorerState !== undefined || props.setExplorerState !== undefined
+  );
+};
+
+const fillPropsWithDefaults = (
+  input: WithOptional<ExplorerProps>,
+  _explorerState: ExplorerNav | null,
+  setExplorerState: React.Dispatch<React.SetStateAction<ExplorerNav | null>>,
+): WithDefaults<ExplorerProps> => {
+  const controlled = isControlled(input);
+  return {
+    ...input,
+    apiURI: input.apiURI || config.apiURI,
+    websocketURI: input.websocketURI || config.websocketURI,
+    darkMode: input.darkMode === undefined ? false : input.darkMode,
+    // In controlled mode, use the provided state (even if null)
+    // In uncontrolled mode, use the internal state
+    explorerState: controlled ? (input.explorerState ?? null) : _explorerState,
+    setExplorerState: input.setExplorerState || setExplorerState,
+    useShadowDOM: input.useShadowDOM || false,
+  };
+};
+
+export type SearchFilterOp =
+  | '='
+  | '$ilike'
+  | '$like'
+  | '$gt'
+  | '$lt'
+  | '$isNull';
+
+export type SearchFilter = [string, SearchFilterOp, any];
+
+export interface ExplorerNav {
+  namespace: string;
+  where?: [string, any];
+  sortAttr?: string;
+  sortAsc?: boolean;
+  filters?: SearchFilter[];
+  limit?: number;
+  page?: number;
+}
+
+export const Explorer = (_props: WithOptional<ExplorerProps>) => {
+  // backup useState if explorer is uncontrolled component
+  const [_explorerState, _setExplorerState] = useState<ExplorerNav | null>(
+    null,
+  );
+  const props: WithDefaults<ExplorerProps> = fillPropsWithDefaults(
+    _props,
+    _explorerState,
+    _setExplorerState,
+  );
+
+  // inside the component avoid setting explorer state directly
+  // if change could be useful for history
+  const { explorerState, setExplorerState } = props;
+
+  const [explorerStateHistory, setExplorerStateHistory] = useState<
+    ExplorerNav[]
+  >([]);
+
+  const pushExplorerState = useCallback(
+    (filter: React.SetStateAction<ExplorerNav>, replace: boolean = false) => {
+      setExplorerStateHistory((prev) => {
+        if (!replace && explorerState) {
+          return [...prev, explorerState];
+        }
+        return prev;
+      });
+      setExplorerState(filter as any);
+    },
+    [explorerState, setExplorerState],
+  );
+
+  const popExplorerState = useCallback(() => {
+    setExplorerStateHistory((prev) => {
+      if (prev.length > 0) {
+        const [last, ...rest] = prev;
+        setExplorerState(last);
+        return rest;
+      }
+      return prev;
+    });
+  }, [setExplorerState]);
+
+  const db = useStableDB({
+    appId: props.appId,
+    apiURI: props.apiURI,
+    websocketURI: props.websocketURI,
+    adminToken: props.adminToken,
+  });
+
+  // Track if this is the first render to avoid resetting on mount
+  const isFirstRender = useRef(true);
+  const prevAppId = useRef(props.appId);
+
+  // Reset explorer history when appId changes (but not on initial mount)
+  // Only reset internal state in uncontrolled mode - in controlled mode,
+  // the parent component manages state resets
+  useEffect(() => {
+    if (isFirstRender.current) {
+      isFirstRender.current = false;
+      return;
+    }
+
+    if (prevAppId.current !== props.appId) {
+      prevAppId.current = props.appId;
+      // Always reset history when app changes
+      setExplorerStateHistory([]);
+      // Only reset state in uncontrolled mode
+      if (!isControlled(_props)) {
+        _setExplorerState(null);
+      }
+    }
+  }, [props.appId, _props]);
+
+  const schemaData = useSchemaQuery(db);
+
+  const contextValue = useMemo(
+    () => ({
+      props,
+      history: {
+        push: pushExplorerState,
+        pop: popExplorerState,
+        items: explorerStateHistory,
+      },
+    }),
+    [props, pushExplorerState, popExplorerState, explorerStateHistory],
+  );
+
+  const Wrapper = props.useShadowDOM ? StyleMe : React.Fragment;
+
+  return (
+    <ExplorerPropsContext.Provider value={contextValue}>
+      <Wrapper>
+        <ErrorBoundary>
+          <ExplorerLayout db={db} namespaces={schemaData.namespaces || []} />
+        </ErrorBoundary>
+      </Wrapper>
+    </ExplorerPropsContext.Provider>
+  );
+};