@sqlrooms/room-shell 0.27.0 → 0.28.0

package/README.md

@@ -1,704 +1,171 @@
-A powerful framework for building and managing data rooms in SQLRooms. This package provides components and utilities for creating, configuring, and managing data rooms with an intuitive user interface.
+Main SQLRooms application shell and default Room slice composition.
 
-## Features
+`@sqlrooms/room-shell` bundles:
 
-- 🏗️ **Room Structure**: Tools for defining and managing room structure
-- 📊 **Data Sources**: Components for connecting to and managing data sources
-- 🧩 **Panel System**: Flexible panel-based UI for room components
-- 🔄 **State Management**: Robust state management using Zustand
-- 📁 **File Handling**: Utilities for processing and managing room files
-- 🧰 **Extensible Architecture**: Easily extend with custom components and panels
+- base room lifecycle (`room-store`)
+- DuckDB slice (`@sqlrooms/duckdb`)
+- layout slice (`@sqlrooms/layout`)
+- React shell UI (`RoomShell`, sidebar/layout/loading components)
+
+Use this package as the default entry point for most SQLRooms apps.
 
 ## Installation
 
 ```bash
-npm install @sqlrooms/room-shell
-# or
-yarn add @sqlrooms/room-shell
+npm install @sqlrooms/room-shell @sqlrooms/duckdb @sqlrooms/ui
 ```
 
-## Basic Usage
-
-### Creating a Room Builder
-
-```tsx
-import {RoomShell} from '@sqlrooms/room-shell';
-
-function MyApp() {
-  return (
-    <RoomShell className="h-screen" roomStore={roomStore}>
-      <RoomShell.Sidebar />
-      <RoomShell.LayoutComposer />
-      <RoomShell.LoadingProgress />
-    </RoomShell>
-  );
-}
-```
-
-### Working with Room State
-
-The room-shell package uses Zustand for state management. You can create a custom store with room-specific state and actions.
+## Quick start
 
 ```tsx
 import {
   createRoomShellSlice,
   createRoomStore,
+  LayoutTypes,
+  RoomShell,
   RoomShellSliceState,
 } from '@sqlrooms/room-shell';
+import {DatabaseIcon} from 'lucide-react';
 
-// Define your custom app state
-type MyRoomState = RoomShellSliceState & {
-  myFeatureData: any[];
-  addItem: (item: any) => void;
-  removeItem: (id: string) => void;
-};
+function DataPanel() {
+  return <div className="p-2">Data panel</div>;
+}
+
+function MainPanel() {
+  return <div className="p-2">Main panel</div>;
+}
 
-// Create a room store with custom state
-export const {roomStore, useRoomStore} = createRoomStore<MyRoomState>(
+type RoomState = RoomShellSliceState;
+
+export const {roomStore, useRoomStore} = createRoomStore<RoomState>(
   (set, get, store) => ({
-    // Base room slice with initial configuration
     ...createRoomShellSlice({
       config: {
-        title: 'My Room',
-        dataSources: [],
+        title: 'My SQLRooms App',
+        dataSources: [
+          {
+            type: 'url',
+            tableName: 'earthquakes',
+            url: 'https://huggingface.co/datasets/sqlrooms/earthquakes/resolve/main/earthquakes.parquet',
+          },
+        ],
       },
       layout: {
         config: {
-          /* layout configuration */
+          type: LayoutTypes.enum.mosaic,
+          nodes: {
+            direction: 'row',
+            first: 'data',
+            second: 'main',
+            splitPercentage: 28,
+          },
         },
         panels: {
-          /* panel definitions */
+          data: {
+            title: 'Data',
+            icon: DatabaseIcon,
+            component: DataPanel,
+            placement: 'sidebar',
+          },
+          main: {
+            title: 'Main',
+            icon: () => null,
+            component: MainPanel,
+            placement: 'main',
+          },
         },
       },
     })(set, get, store),
-
-    // Custom state and actions
-    myFeatureData: [],
-    addItem: (item) =>
-      set((state) => ({
-        myFeatureData: [...state.myFeatureData, item],
-      })),
-    removeItem: (id) =>
-      set((state) => ({
-        myFeatureData: state.myFeatureData.filter((item) => item.id !== id),
-      })),
   }),
 );
 
-// Use the store in a component with selector for better performance
-function MyComponent() {
-  // Use selectors for better performance
-  const myFeatureData = useRoomStore((state) => state.myFeatureData);
-  const addItem = useRoomStore((state) => state.addItem);
-
+export function App() {
   return (
-    <div>
-      <h2>My Items ({myFeatureData.length})</h2>
-      <button onClick={() => addItem({id: Date.now(), name: 'New Item'})}>
-        Add Item
-      </button>
-      {/* Render items */}
-    </div>
+    <RoomShell roomStore={roomStore} className="h-screen">
+      <RoomShell.Sidebar />
+      <RoomShell.LayoutComposer />
+      <RoomShell.LoadingProgress />
+      <RoomShell.CommandPalette />
+    </RoomShell>
   );
 }
 ```
 
-### Persisting Room Configuration
-
-The room configuration is designed to be persisted between sessions. You can use the `persistSliceConfigs` helper to save the configuration to localStorage or any other storage:
-
-```tsx
-import {
-  createRoomShellSlice,
-  createRoomStore,
-  RoomShellSliceState,
-  BaseRoomConfig,
-  LayoutConfig,
-  persistSliceConfigs,
-} from '@sqlrooms/room-shell';
-
-// Define your custom app state
-type MyRoomState = RoomShellSliceState & {
-  myFeatureData: any[];
-  addItem: (item: any) => void;
-};
-
-// Create a store with persistence
-export const {roomStore, useRoomStore} = createRoomStore<MyRoomState>(
-  persistSliceConfigs(
-    {
-      name: 'my-room-storage',
-      sliceConfigSchemas: {
-        room: BaseRoomConfig,
-        layout: LayoutConfig,
-      },
-    },
-    (set, get, store) => ({
-      // Base room slice
-      ...createRoomShellSlice({
-        config: {
-          title: 'My Room',
-          dataSources: [],
-        },
-        layout: {
-          config: {
-            /* layout configuration */
-          },
-          panels: {
-            /* panel definitions */
-          },
-        },
-      })(set, get, store),
-
-      // Custom state and actions
-      myFeatureData: [],
-      addItem: (item) =>
-        set((state) => ({
-          myFeatureData: [...state.myFeatureData, item],
-        })),
-    }),
-  ),
-);
-```
-
-### Integrating Multiple Feature Slices
-
-For larger applications, you can organize your state into feature slices:
-
-```tsx
-import {
-  createRoomShellSlice,
-  createRoomStore,
-  RoomShellSliceState,
-} from '@sqlrooms/room-shell';
-import {createMyFeatureSlice, MyFeatureState} from './myFeatureSlice';
-import {
-  createAnotherFeatureSlice,
-  AnotherFeatureState,
-} from './anotherFeatureSlice';
-
-// Combined app state type
-type MyRoomState = RoomShellSliceState & MyFeatureState & AnotherFeatureState;
-
-// Create a store with multiple slices
-export const {roomStore, useRoomStore} = createRoomStore<MyRoomState>(
-  (set, get, store) => ({
-    // Base room slice
-    ...createRoomShellSlice({
-      config: {
-        /* initial config */
-      },
-      layout: {
-        config: {
-          /* layout configuration */
-        },
-        panels: {
-          /* panel definitions */
-        },
-      },
-    })(set, get, store),
-
-    // Feature slices
-    ...createMyFeatureSlice()(set, get, store),
-    ...createAnotherFeatureSlice({
-      // Feature-specific options
-      customOption: 'value',
-    })(set, get, store),
-  }),
-);
-```
-
-### Managing Data Sources
+## Common room actions
 
 ```tsx
-import {
-  FileDataSourcesPanel,
-  TablesListPanel,
-  DataSourceType,
-} from '@sqlrooms/room-shell';
+import {useRoomStore} from './store';
+import {Button} from '@sqlrooms/ui';
 
-function DataSourcesSection() {
-  // Use selectors for better performance
+function RoomActions() {
+  const setRoomTitle = useRoomStore((state) => state.room.setRoomTitle);
   const addDataSource = useRoomStore((state) => state.room.addDataSource);
+  const removeDataSource = useRoomStore((state) => state.room.removeDataSource);
   const addRoomFile = useRoomStore((state) => state.room.addRoomFile);
 
-  const handleFileDrop = async (files) => {
-    for (const file of files) {
-      await addRoomFile(file);
-    }
-  };
-
-  const handleAddCsvUrl = (url) => {
-    addDataSource({
-      type: DataSourceType.url,
-      url,
-      tableName: 'data_from_url',
-    });
-  };
-
-  const handleAddSqlQuery = (query) => {
-    addDataSource({
-      type: DataSourceType.sqlQuery,
-      query,
-      tableName: 'query_results',
-    });
-  };
-
   return (
-    <div className="grid grid-cols-2 gap-4">
-      <FileDataSourcesPanel onFileDrop={handleFileDrop} />
-      <TablesListPanel />
-      <button onClick={() => handleAddCsvUrl('https://example.com/data.csv')}>
-        Add CSV from URL
-      </button>
+    <div className="flex gap-2">
+      <Button onClick={() => setRoomTitle('Updated title')}>Rename room</Button>
+      <Button
+        onClick={() =>
+          void addDataSource({
+            type: 'sql',
+            tableName: 'top_quakes',
+            sqlQuery:
+              'SELECT * FROM earthquakes ORDER BY Magnitude DESC LIMIT 100',
+          })
+        }
+      >
+        Add SQL data source
+      </Button>
+      <Button onClick={() => void removeDataSource('top_quakes')}>
+        Remove SQL data source
+      </Button>
+      <Button
+        onClick={async () => {
+          const file = new File(['id,name\n1,Alice'], 'people.csv', {
+            type: 'text/csv',
+          });
+          await addRoomFile(file);
+        }}
+      >
+        Add file
+      </Button>
     </div>
   );
 }
 ```
 
-### Creating Custom Panels
-
-```tsx
-import {RoomPanel, RoomPanelHeader} from '@sqlrooms/room-shell';
-
-function CustomPanel({title, children}) {
-  return (
-    <RoomPanel>
-      <RoomPanelHeader title={title} />
-      <div className="p-4">{children}</div>
-    </RoomPanel>
-  );
-}
-```
-
-## RoomStore API Reference
-
-The RoomStore is the core of the room-shell package. It provides a comprehensive set of properties and methods for managing room state.
-
-### State Properties
-
-#### `room.config`
-
-The room configuration, which can be persisted between sessions.
-
-```tsx
-const config = useRoomStore((state) => state.room.config);
-console.log(config.title); // Access room title
-```
-
-#### `schema`
-
-The database schema name used for the room.
-
-```tsx
-const schema = useRoomStore((state) => state.room.schema);
-```
-
-#### `tasksProgress`
-
-A record of task progress information, useful for displaying loading indicators.
-
-```tsx
-const tasksProgress = useRoomStore((state) => state.room.tasksProgress);
-// Example: { "init-db": { message: "Initializing database...", progress: 0.5 } }
-```
-
-#### `roomId`
-
-The unique identifier for the room, undefined for new rooms.
-
-```tsx
-const roomId = useRoomStore((state) => state.room.roomId);
-```
-
-#### `panels`
-
-A record of panel information, including title, icon, component, and placement.
-
-```tsx
-const panels = useRoomStore((state) => state.room.panels);
-// Example: { "data-sources": { title: "Data Sources", icon: DatabaseIcon, ... } }
-```
-
-#### `isReadOnly`
-
-Whether the room is in read-only mode.
-
-```tsx
-const isReadOnly = useRoomStore((state) => state.room.isReadOnly);
-```
-
-#### `tables`
-
-An array of data tables available in the room.
-
-```tsx
-const tables = useRoomStore((state) => state.room.tables);
-// Access table schemas and metadata
-```
-
-#### `roomFiles`
-
-An array of room file information.
-
-```tsx
-const roomFiles = useRoomStore((state) => state.room.roomFiles);
-```
-
-#### `roomFilesProgress`
-
-A record of file processing progress information.
-
-```tsx
-const roomFilesProgress = useRoomStore((state) => state.room.roomFilesProgress);
-```
-
-#### `lastSavedConfig`
-
-The last saved room configuration, used to check for unsaved changes.
-
-```tsx
-const lastSavedConfig = useRoomStore((state) => state.room.lastSavedConfig);
-```
-
-#### `initialized`
-
-Whether the room has been initialized.
-
-```tsx
-const initialized = useRoomStore((state) => state.room.initialized);
-```
-
-#### `isDataAvailable`
-
-Whether the room data has been loaded.
-
-```tsx
-const isDataAvailable = useRoomStore((state) => state.room.isDataAvailable);
-```
-
-#### `dataSourceStates`
-
-A record of data source states by table name.
-
-```tsx
-const dataSourceStates = useRoomStore((state) => state.room.dataSourceStates);
-```
-
-#### `tableRowCounts`
-
-A record of row counts by table name.
-
-```tsx
-const tableRowCounts = useRoomStore((state) => state.room.tableRowCounts);
-```
-
-### Methods
-
-#### `initialize()`
-
-Initialize the room state.
-
-```tsx
-const initialize = useRoomStore((state) => state.room.initialize);
-await initialize();
-```
-
-#### `setTaskProgress(id, taskProgress)`
-
-Set the progress of a task.
-
-```tsx
-const setTaskProgress = useRoomStore((state) => state.room.setTaskProgress);
-setTaskProgress('my-task', {message: 'Processing...', progress: 0.5});
-```
-
-#### `getLoadingProgress()`
-
-Get the current loading progress.
-
-```tsx
-const getLoadingProgress = useRoomStore(
-  (state) => state.room.getLoadingProgress,
-);
-const progress = getLoadingProgress();
-```
-
-#### `setRoomConfig(config)`
-
-Set the room configuration.
-
-```tsx
-const setRoomConfig = useRoomStore((state) => state.room.setRoomConfig);
-const config = useRoomStore((state) => state.config);
-setRoomConfig({...config, title: 'New Title'});
-```
-
-#### `setLastSavedConfig(config)`
-
-Set the last saved room configuration.
-
-```tsx
-const setLastSavedConfig = useRoomStore(
-  (state) => state.room.setLastSavedConfig,
-);
-const config = useRoomStore((state) => state.config);
-setLastSavedConfig(config);
-```
-
-#### `hasUnsavedChanges()`
-
-Check if the room has unsaved changes.
-
-```tsx
-const hasUnsavedChanges = useRoomStore((state) => state.room.hasUnsavedChanges);
-if (hasUnsavedChanges()) {
-  // Prompt user to save changes
-}
-```
-
-#### `setLayout(layout)`
-
-Set the room layout configuration.
-
-```tsx
-const setLayout = useRoomStore((state) => state.room.setLayout);
-setLayout(newLayout);
-```
-
-#### `togglePanel(panel, show)`
-
-Toggle the visibility of a panel.
-
-```tsx
-const togglePanel = useRoomStore((state) => state.room.togglePanel);
-togglePanel('data-sources', true); // Show the data sources panel
-```
-
-#### `togglePanelPin(panel)`
-
-Toggle the pin state of a panel.
-
-```tsx
-const togglePanelPin = useRoomStore((state) => state.room.togglePanelPin);
-togglePanelPin('data-sources');
-```
-
-#### `addOrUpdateSqlQueryDataSource(tableName, query, oldTableName)`
-
-Add or update a SQL query data source.
-
-```tsx
-const addOrUpdateSqlQueryDataSource = useRoomStore(
-  (state) => state.room.addOrUpdateSqlQueryDataSource,
-);
-await addOrUpdateSqlQueryDataSource(
-  'filtered_data',
-  'SELECT * FROM data WHERE value > 10',
-);
-```
-
-#### `removeSqlQueryDataSource(tableName)`
-
-Remove a SQL query data source.
-
-```tsx
-const removeSqlQueryDataSource = useRoomStore(
-  (state) => state.room.removeSqlQueryDataSource,
-);
-await removeSqlQueryDataSource('filtered_data');
-```
-
-#### `addRoomFile(info, desiredTableName)`
-
-Add a room file.
-
-```tsx
-const addRoomFile = useRoomStore((state) => state.room.addRoomFile);
-const dataTable = await addRoomFile(file, 'my_data');
-```
-
-#### `removeRoomFile(pathname)`
-
-Remove a room file.
-
-```tsx
-const removeRoomFile = useRoomStore((state) => state.room.removeRoomFile);
-removeRoomFile('/path/to/file.csv');
-```
-
-#### `maybeDownloadDataSources()`
-
-Download data sources if needed.
-
-```tsx
-const maybeDownloadDataSources = useRoomStore(
-  (state) => state.room.maybeDownloadDataSources,
-);
-await maybeDownloadDataSources();
-```
-
-#### `setRoomFiles(info)`
-
-Set the room files.
-
-```tsx
-const setRoomFiles = useRoomStore((state) => state.room.setRoomFiles);
-setRoomFiles(fileInfoArray);
-```
-
-#### `setRoomFileProgress(pathname, fileState)`
-
-Set the progress of a room file.
-
-```tsx
-const setRoomFileProgress = useRoomStore(
-  (state) => state.room.setRoomFileProgress,
-);
-setRoomFileProgress('/path/to/file.csv', {status: 'processing'});
-```
-
-#### `addTable(tableName, data)`
-
-Add a table to the room.
-
-```tsx
-const addTable = useRoomStore((state) => state.db.addTable);
-await addTable('my_table', records);
-```
-
-#### `addDataSource(dataSource, status)`
-
-Add a data source to the room.
-
-```tsx
-const addDataSource = useRoomStore((state) => state.room.addDataSource);
-await addDataSource({
-  type: 'url',
-  url: 'https://example.com/data.csv',
-  tableName: 'external_data',
-});
-```
-
-#### `getTable(tableName)`
-
-Get a table by name.
-
-```tsx
-const getTable = useRoomStore((state) => state.room.getTable);
-const table = getTable('my_table');
-```
-
-#### `setTables(dataTable)`
-
-Set the room tables.
-
-```tsx
-const setTables = useRoomStore((state) => state.room.setTables);
-await setTables(tableArray);
-```
-
-#### `setTableRowCount(tableName, rowCount)`
-
-Set the row count for a table.
-
-```tsx
-const setTableRowCount = useRoomStore((state) => state.room.setTableRowCount);
-setTableRowCount('my_table', 1000);
-```
-
-#### `setRoomTitle(title)`
-
-Set the room title.
-
-```tsx
-const setRoomTitle = useRoomStore((state) => state.room.setRoomTitle);
-setRoomTitle('My Awesome Room');
-```
-
-#### `setDescription(description)`
-
-Set the room description.
-
-```tsx
-const setDescription = useRoomStore((state) => state.room.setDescription);
-setDescription('This is a description of my room');
-```
-
-#### `areDatasetsReady()`
-
-Check if all datasets are ready.
-
-```tsx
-const areDatasetsReady = useRoomStore((state) => state.room.areDatasetsReady);
-if (areDatasetsReady()) {
-  // Proceed with data operations
-}
-```
-
-#### `findTableByName(tableName)`
+## Persistence
 
-Find a table by name.
+Use `persistSliceConfigs` with schemas:
 
 ```tsx
-const findTableByName = useRoomStore((state) => state.room.findTableByName);
-const table = findTableByName('my_table');
-```
-
-#### `updateReadyDataSources()`
-
-Update the status of all data sources based on the current tables.
-
-```tsx
-const updateReadyDataSources = useRoomStore(
-  (state) => state.room.updateReadyDataSources,
-);
-await updateReadyDataSources();
-```
-
-#### `onDataUpdated()`
-
-Called when data has been updated.
-
-```tsx
-const onDataUpdated = useRoomStore((state) => state.room.onDataUpdated);
-await onDataUpdated();
-```
-
-#### `areViewsReadyToRender()`
-
-Check if views are ready to render.
-
-```tsx
-const areViewsReadyToRender = useRoomStore(
-  (state) => state.room.areViewsReadyToRender,
-);
-if (areViewsReadyToRender()) {
-  // Render views
-}
-```
-
-#### `refreshTableSchemas()`
+import {
+  BaseRoomConfig,
+  LayoutConfig,
+  createRoomStore,
+  persistSliceConfigs,
+} from '@sqlrooms/room-shell';
 
-Refresh table schemas from the database.
+const persistence = {
+  name: 'my-room-storage',
+  sliceConfigSchemas: {
+    room: BaseRoomConfig,
+    layout: LayoutConfig,
+  },
+};
 
-```tsx
-const refreshTableSchemas = useRoomStore(
-  (state) => state.room.refreshTableSchemas,
+createRoomStore(
+  persistSliceConfigs(persistence, (set, get, store) => ({
+    // compose slices here
+  })),
 );
-const updatedTables = await refreshTableSchemas();
 ```
 
-## Advanced Features
+## Related packages
 
-- **Custom State Slices**: Extend the room state with custom slices
-- **Task Management**: Built-in task progress tracking
-- **Panel Configuration**: Configure and arrange panels dynamically
-- **Data Source Integration**: Connect to various data sources
-- **File Processing**: Process and transform data files
-
-For more information, visit the SQLRooms documentation.
-
-```
-
-```
+- `@sqlrooms/sql-editor`
+- `@sqlrooms/ai`
+- `@sqlrooms/mosaic`
+- `@sqlrooms/vega`