@osdk/react-components 0.2.0-beta.2 → 0.2.0-beta.20

package/AGENTS.md

@@ -0,0 +1,105 @@
+# @osdk/react-components
+
+Pre-built UI components for OSDK data. Requires `@osdk/react` (see the `@osdk/react` package's `AGENTS.md` for hooks and provider setup).
+
+## Setup
+
+All components import from `@osdk/react-components/experimental`. Requires `OsdkProvider2` from `@osdk/react/experimental`.
+
+### Provider (required)
+
+```tsx
+import { OsdkProvider2 } from "@osdk/react/experimental";
+import { client } from "./client";
+
+function App() {
+  return (
+    <OsdkProvider2 client={client}>
+      <MyApp />
+    </OsdkProvider2>
+  );
+}
+```
+
+### CSS (required)
+
+```css
+@layer osdk.tokens, osdk.components;
+@import "@osdk/react-components-styles" layer(osdk.tokens);
+@import "@osdk/react-components/styles.css" layer(osdk.components);
+
+.root {
+  isolation: isolate;
+}
+```
+
+## ObjectTable
+
+```tsx
+import { ObjectTable } from "@osdk/react-components/experimental";
+import { Employee } from "@your-osdk-package";
+
+function EmployeeDirectory() {
+  return <ObjectTable objectType={Employee} />;
+}
+```
+
+### Key Props
+
+| Prop                         | Type                                 | Description                                                         |
+| ---------------------------- | ------------------------------------ | ------------------------------------------------------------------- |
+| `objectType`                 | ObjectType                           | **Required.** The OSDK object type to display.                      |
+| `columnDefinitions`          | `ColumnDefinition[]`                 | Column config: visibility, order, custom renderers, pinning, width. |
+| `enableFiltering`            | boolean                              | Allow user filtering (default: true)                                |
+| `enableOrdering`             | boolean                              | Allow user sorting (default: true)                                  |
+| `enableColumnPinning`        | boolean                              | Allow column pinning (default: true)                                |
+| `enableColumnResizing`       | boolean                              | Allow column resizing (default: true)                               |
+| `enableColumnConfig`         | boolean                              | Show column config dialog (default: true)                           |
+| `selectionMode`              | `"single"` / `"multiple"` / `"none"` | Row selection mode (default: "none")                                |
+| `orderBy` / `defaultOrderBy` | `OrderBy<Q>[]`                       | Controlled/uncontrolled sorting                                     |
+| `filter`                     | WhereClause                          | Controlled filtering                                                |
+| `rowHeight`                  | number                               | Row height in pixels (default: 40)                                  |
+| `renderCellContextMenu`      | function                             | Custom right-click menu                                             |
+
+### Column Definition
+
+```ts
+type ColumnDefinition = {
+  locator:
+    | { type: "property"; id: PropertyKeys<Q> }
+    | {
+      type: "rdp";
+      id: keyof RDPs;
+      creator: DerivedProperty.Creator<Q, RDPs[keyof RDPs]>;
+    }
+    | { type: "function"; id: keyof FunctionColumns }
+    | { type: "custom"; id: string };
+  renderCell?: (
+    object: Osdk.Instance<Q>,
+    locator: ColumnDefinitionLocator<Q>,
+  ) => React.ReactNode;
+  renderHeader?: () => React.ReactNode;
+  width?: number;
+  pinned?: "left" | "right" | "none";
+  isVisible?: boolean;
+  orderable?: boolean;
+  columnName?: string;
+};
+```
+
+### ColumnConfigDialog
+
+Standalone dialog for column visibility/ordering:
+
+```tsx
+import { ColumnConfigDialog } from "@osdk/react-components/experimental";
+
+<ColumnConfigDialog
+  isOpen={isOpen}
+  onClose={() => setIsOpen(false)}
+  columnOptions={[{ id: "fullName", name: "Full Name" }]}
+  currentVisibility={{ fullName: true }}
+  currentColumnOrder={["fullName"]}
+  onApply={(columns) => {/* [{ columnId, isVisible }] */}}
+/>;
+```

package/CHANGELOG.md

@@ -1,5 +1,238 @@
 # @osdk/react-components
 
+## 0.2.0-beta.20
+
+### Minor Changes
+
+- 9ff2eca: Add function-backed column query
+- 6516ff9: Fix multiple setData calls
+- bc46400: Add skeleton loading states and polish checkbox list, histogram, and range filter inputs
+- 7a3c43d: feat(pdf): pdf-viewer component
+- 532d0d7: Fix lint errors
+- 074a754: Display function-backed column
+
+### Patch Changes
+
+- Updated dependencies [4bb9769]
+  - @osdk/api@2.8.0-beta.23
+  - @osdk/client@2.8.0-beta.23
+  - @osdk/react@0.10.0-beta.10
+
+## 0.2.0-beta.19
+
+### Minor Changes
+
+- 9f76365: Follow-up cleanups from ActionForm PR
+- dbbfb6f: Add experimental ActionForm component with field renderers, form state hook, and tests
+- aa908e4: Redesign filter list collapse into separate render tree and simplify header layout
+
+### Patch Changes
+
+- Updated dependencies [dbbfb6f]
+- Updated dependencies [cbfa135]
+- Updated dependencies [f4604c2]
+  - @osdk/react@0.10.0-beta.10
+  - @osdk/client@2.8.0-beta.22
+  - @osdk/api@2.8.0-beta.22
+
+## 0.2.0-beta.18
+
+### Minor Changes
+
+- fcc4971: Refactor filter list where clause generation for consistent exclude wrapping and integer clamping
+- 29095f5: fix where clause generation for compound property filters and remove useEffect in useFilterListState
+- 7347abe: Update README
+- a198fc5: Fix header cell not aligned
+- 00677eb: Upgrade Storybook to v10 and add MCP addon.
+
+### Patch Changes
+
+- Updated dependencies [c40444b]
+- Updated dependencies [dda14be]
+  - @osdk/client@2.8.0-beta.21
+  - @osdk/react@0.10.0-beta.9
+  - @osdk/api@2.8.0-beta.21
+
+## 0.2.0-beta.17
+
+### Minor Changes
+
+- 7542c11: add remove button to filter list items and memoize dnd accessibility props
+- 05618c3: Add validation state to editable cell
+
+### Patch Changes
+
+- @osdk/api@2.8.0-beta.20
+- @osdk/client@2.8.0-beta.20
+- @osdk/react@0.10.0-beta.8
+
+## 0.2.0-beta.16
+
+### Minor Changes
+
+- 06095fa: Restructure FilterList into base and osdk layers
+- f6649a5: add collapsible panel, select all, include/exclude toggle, per-item colors, histogram display modes, and session persistence support to filter list
+- 1135a27: Update Blueprint css import
+
+### Patch Changes
+
+- @osdk/api@2.8.0-beta.19
+- @osdk/client@2.8.0-beta.19
+- @osdk/react@0.10.0-beta.8
+
+## 0.2.0-beta.15
+
+### Minor Changes
+
+- 02a095b: Support select all in controlled mode
+
+### Patch Changes
+
+- Updated dependencies [c8384de]
+  - @osdk/client@2.8.0-beta.18
+  - @osdk/api@2.8.0-beta.18
+  - @osdk/react@0.10.0-beta.8
+
+## 0.2.0-beta.14
+
+### Minor Changes
+
+- fb9383c: Fix table crashes on remount
+
+## 0.2.0-beta.13
+
+### Minor Changes
+
+- 76ee40a: Fix column resize and value change ux
+- edbe438: FilterList base components with drag-and-drop sorting and tokenized styling
+
+### Patch Changes
+
+- Updated dependencies [8c30908]
+  - @osdk/client@2.8.0-beta.17
+  - @osdk/api@2.8.0-beta.17
+  - @osdk/react@0.10.0-beta.8
+
+## 0.2.0-beta.12
+
+### Minor Changes
+
+- 9720083: Add AGENTS.md files for AI IDE context
+
+### Patch Changes
+
+- Updated dependencies [9720083]
+- Updated dependencies [09e5659]
+- Updated dependencies [8a82492]
+- Updated dependencies [2ebe62c]
+  - @osdk/react@0.10.0-beta.8
+  - @osdk/client@2.8.0-beta.16
+  - @osdk/api@2.8.0-beta.16
+
+## 0.2.0-beta.11
+
+### Minor Changes
+
+- 447e29d: Update editable table UX and API to pass the entire row data on edit
+
+## 0.2.0-beta.10
+
+### Minor Changes
+
+- b4bf087: add complex and aggregation filter input components
+- 0bf4c53: add e2e sandbox filter list demos and remove unused filter types
+- 35f2f1a: Add Media inputs/outputs for Queries
+
+### Patch Changes
+
+- Updated dependencies [9156827]
+- Updated dependencies [e64bf0b]
+- Updated dependencies [baba327]
+- Updated dependencies [d1ad4d1]
+- Updated dependencies [35f2f1a]
+- Updated dependencies [71e28ef]
+  - @osdk/react@0.10.0-beta.7
+  - @osdk/client@2.8.0-beta.14
+  - @osdk/api@2.8.0-beta.14
+
+## 0.2.0-beta.9
+
+### Minor Changes
+
+- 4187b2b: Fix shift click to select from last selected and header menu styles
+
+## 0.2.0-beta.8
+
+### Minor Changes
+
+- 993c023: ObjectTable supports objectSet input
+
+### Patch Changes
+
+- Updated dependencies [993c023]
+- Updated dependencies [8825f8c]
+  - @osdk/react@0.10.0-beta.6
+  - @osdk/client@2.8.0-beta.12
+  - @osdk/api@2.8.0-beta.12
+
+## 0.2.0-beta.7
+
+### Minor Changes
+
+- 52b70aa: Fix onRowClick triggered on row selection
+
+## 0.2.0-beta.6
+
+### Minor Changes
+
+- 9893b41: Add storybook
+
+## 0.2.0-beta.5
+
+### Minor Changes
+
+- dba18e0: Fix css build
+
+### Patch Changes
+
+- @osdk/api@2.8.0-beta.8
+- @osdk/client@2.8.0-beta.8
+- @osdk/react@0.10.0-beta.4
+
+## 0.2.0-beta.4
+
+### Minor Changes
+
+- 9c54ee5: Support editable cell
+
+### Patch Changes
+
+- Updated dependencies [4cd7389]
+  - @osdk/client@2.8.0-beta.7
+  - @osdk/api@2.8.0-beta.7
+  - @osdk/react@0.10.0-beta.4
+
+## 0.2.0-beta.3
+
+### Minor Changes
+
+- 50bd461: add combobox, select, and switch base components
+- 727fd0e: fix dual @types/react version mismatch
+- 4c7884f: Add custom column, multi column sort and column config
+- 4ffe6f5: add filter list state management and where clause builder
+
+### Patch Changes
+
+- Updated dependencies [8c60682]
+- Updated dependencies [15e1686]
+- Updated dependencies [727fd0e]
+- Updated dependencies [c9d954d]
+- Updated dependencies [044eb80]
+- Updated dependencies [9d234b9]
+  - @osdk/client@2.8.0-beta.6
+  - @osdk/react@0.10.0-beta.4
+  - @osdk/api@2.8.0-beta.6
+
 ## 0.2.0-beta.2
 
 ### Minor Changes

package/README.md

@@ -1,5 +1,7 @@
 # @osdk/react-components
 
+> **⚠️ Beta Release**: This package is currently in beta. Please use the latest beta version for the most up-to-date features and fixes.
+
 React components for building Foundry applications. These components are Ontology-aware — pass in OSDK entities, and they handle data loading, caching, and state management automatically.
 
 Built on top of [@osdk/react](../react), these components use OSDK hooks internally to provide ready-to-use UI elements. While @osdk/react gives you low-level hooks for data fetching, @osdk/react-components provides UI widgets for common patterns like tables and forms.
@@ -12,7 +14,7 @@ Run the command to install:
 - @osdk/react-components-styles - The default styles for the components
 
 ```sh
-npm install @osdk/react-components @osdk/react-components-styles
+npm install @osdk/react-components@beta @osdk/react-components-styles@beta
 ```
 
 **Peer Dependencies:**
@@ -23,24 +25,42 @@ The following peer dependencies are required:
 npm install react react-dom classnames @osdk/react @osdk/client @osdk/api
 ```
 
-- `react` and `react-dom` - React 17, 18, or 19
+- `react`, `@types/react`, `react-dom` - React 17, 18, or 19
 - `classnames` - Utility for conditionally joining CSS class names
 - `@osdk/react`, `@osdk/api`, `@osdk/client` - The packages required for data-handling
 
-For TypeScript users, also install `@types/react`.
-
 **Prerequisites:**
 
 - A configured OSDK client
-- An OsdkProvider wrapping your application
+- An OsdkProvider2 wrapping your application
 
 ## Setup
 
+### App Setup
+
+**REQUIRED:** Wrap app with OsdkProvider2:
+
+```tsx
+import { createClient } from "@osdk/client";
+import { OsdkProvider2 } from "@osdk/react/experimental";
+
+const client = createClient(/* config */);
+
+function App() {
+  return <OsdkProvider2 client={client}>{/* components */}</OsdkProvider2>;
+}
+```
+
+### CSS Setup
+
 Add this to your application's entry css file (e.g., `index.css` or `index.scss`):
 
 ```css
 /* index.css */
-@import "@osdk/react-components/styles.css";
+@layer osdk.tokens, osdk.components;
+
+@import "@osdk/react-components-styles" layer(osdk.tokens);
+@import "@osdk/react-components/styles.css" layer(osdk.components);
 
 .root {
   isolation: isolate;
@@ -49,17 +69,105 @@ Add this to your application's entry css file (e.g., `index.css` or `index.scss`
 
 The `.root` isolation is required for Base UI portals. See https://base-ui.com/react/overview/quick-start#portals
 
+Using `@layer` ensures proper CSS cascade ordering - component styles are loaded before token styles, allowing tokens to override component defaults when needed.
+
 ## Components
 
 > **Note:** This package is under active development. Not all components listed below are available yet.
 
 The components that this package will provide are:
 
-| Component     | Description                                                                        |
-| ------------- | ---------------------------------------------------------------------------------- |
-| `ObjectTable` | Displays an Object Set as a sortable, paginated table                              |
-| `FilterList`  | Visualize a high-level summary of objects data to allow users to filter that data. |
-| `ActionForm`  | Auto-generated form for executing Ontology Actions                                 |
+| Component     | Description                                                                        | Documentation                  |
+| ------------- | ---------------------------------------------------------------------------------- | ------------------------------ |
+| `ObjectTable` | Displays an Object Set as a sortable, paginated table with inline editing support  | [Guide](./docs/ObjectTable.md) |
+| `FilterList`  | Visualize a high-level summary of objects data to allow users to filter that data. | -                              |
+| `ActionForm`  | Auto-generated form for executing Ontology Actions                                 | -                              |
+
+## Component Architecture
+
+This package follows a 2-layer architecture pattern to maximize flexibility and reusability:
+
+### Architecture Overview
+
+1. **OSDK Component Layer** (e.g., `ObjectTable`)
+   - Handles data fetching and processing using @osdk/react hooks
+   - Converts OSDK types to primitive data structures
+   - Manages OSDK-specific operations like filtering and actions
+   - No styling or component interactions
+
+2. **Base Component Layer** (e.g., `BaseTable`)
+   - Pure component layer with no OSDK imports
+   - Contains all component interactions and styling
+   - Accepts primitive props like `string[]`, arrays, and objects
+   - Can be reused with custom data fetching layers
+
+### Example: ObjectTable and BaseTable
+
+```tsx
+// ObjectTable - Data layer
+- Fetches OSDK object data using useOsdkObjects
+- Handles OSDK-specific operations (filtering, sorting, actions)
+- Converts OSDK objects to table row data
+- Manages object property metadata
+- Passes primitive data to BaseTable
+
+// BaseTable - Component layer  
+- Pure table component with no OSDK imports
+- Handles all UI interactions (sorting, selection, editing)
+- Manages component state
+```
+
+### Benefits
+
+- **Flexibility**: Users can build custom components using the Base layer with their own data sources
+- **Separation of Concerns**: Data fetching logic is cleanly separated from UI logic
+- **Reusability**: Base components can be exported and used independently
+- **Testing**: Base components can be tested without OSDK dependencies
+
+### Implementation Guidelines
+
+When building new components:
+
+1. Start with the Base component focusing on interactions and styling
+2. Create the OSDK wrapper that handles data fetching and type conversion
+3. Keep the Base component API simple using primitive types
+4. Document both layers for users who want to customize
+
+## Folder Structure
+
+The codebase is organized to support the 2-layer architecture:
+
+```
+src/
+├── base-components/         # Reusable UI primitives (internal use only)
+│   ├── select/
+│   ├── checkbox/
+│   ├── dialog/
+│   └── ...
+├── object-table/           # OSDK component folder
+│   ├── ObjectTable.tsx     # OSDK data layer component
+│   ├── Table.tsx           # Base component (exported as BaseTable)
+│   ├── hooks/              # React hooks for table functionality
+│   ├── utils/              # Helper utilities and types
+│   └── components/         # Supporting React components
+└── public/
+    └── experimental.ts     # Public API exports
+```
+
+### Export Strategy
+
+- **OSDK Components**: Exported through `experimental.ts` (e.g., `ObjectTable`, `FilterList`)
+- **Base Components**: Select base components are exported for advanced use cases (e.g., `BaseTable`, `BaseFilterList`)
+- **UI Primitives**: The `base-components/` folder contains internal UI primitives that are **NOT exported**
+
+### Why Not Export UI Primitives?
+
+This package focuses on complex, Ontology-aware components with built-in data fetching. For simple UI components (buttons, inputs, dialogs), users should use established component libraries like Blueprint.js or their preferred design system. This approach:
+
+- Keeps the package focused on its core value proposition
+- Avoids duplicating well-solved UI problems
+- Reduces maintenance burden
+- Encourages consistent use of existing design systems
 
 ## Custom Styling
 
@@ -71,7 +179,7 @@ See `@osdk/react-components-styles` README on how to apply custom themes and sty
 
 ```ts
 import { ObjectTable } from "@osdk/react-components/experimental";
-import { $, Employee } from "@your-osdk-package";
+import { Employee } from "@your-osdk-package";
 
 function EmployeeDirectory() {
   return (
@@ -82,27 +190,24 @@ function EmployeeDirectory() {
 }
 ```
 
+## Development Workflow
+
+1. In packages/react-components, run `pnpm install` to install the dependencies.
+2. Run `pnpm transpileAllDeps` to transpile all dependencies in this repo.
+3. To run tests, run `pnpm test`
+
 ### Running the Example People App
 
 The examples are added to `packages/e2e.sandbox.peopleapp`, so we need to run the example app.
 
 #### Steps:
 
-1. Create a .env.local file with the content below in packages/e2e.sandbox.peopleapp:
-
-```
-VITE_FOUNDRY_URL=https://swirl.palantirfoundry.com
-VITE_FOUNDRY_CLIENT_ID=<insert_client_id>
-VITE_FOUNDRY_CLIENT_SECRET=<insert_token>
-VITE_FOUNDRY_REDIRECT_URL=http://localhost:8080/auth/callback
-```
-
-2. Get VITE_FOUNDRY_CLIENT_ID from "https://swirl.palantirfoundry.com/workspace/developer-console/app/ri.third-party-applications.main.application.91b973ac-e504-4322-95b4-4962b60495fe/oauth" under App Credentials > Client ID.
+1. Create a .env.local file based on `.env.local.sample` in packages/e2e.sandbox.peopleapp:
 
-3. Transpile @osdk/react-components and its dependencies
+2. Transpile all dependencies of peopleapp
 
 ```
-pnpm --filter @osdk/react-components transpileAllDeps && pnpm --filter @osdk/react-components transpileBrowser
+pnpm --filter @osdk/e2e.sandbox.peopleapp transpileAllDeps
 ```
 
 4. Run the people app

package/build/browser/action-form/ActionForm.js

@@ -0,0 +1,113 @@
+function _extends() { return _extends = Object.assign ? Object.assign.bind() : function (n) { for (var e = 1; e < arguments.length; e++) { var t = arguments[e]; for (var r in t) ({}).hasOwnProperty.call(t, r) && (n[r] = t[r]); } return n; }, _extends.apply(null, arguments); }
+/*
+ * Copyright 2025 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { useOsdkMetadata } from "@osdk/react";
+import { useOsdkAction } from "@osdk/react/experimental";
+import React, { useCallback, useEffect, useMemo } from "react";
+import { typedReactMemo } from "../shared/typedMemo.js";
+import { BaseForm } from "./BaseForm.js";
+import { coerceFieldValue } from "./utils/coerceFieldValue.js";
+import { getDefaultFieldDefinitions } from "./utils/getDefaultFieldDefinitions.js";
+const EMPTY_FIELD_DEFINITIONS = [];
+export const ActionForm = typedReactMemo(function ({
+  actionDefinition,
+  formTitle,
+  formFieldDefinitions,
+  formState: controlledFormState,
+  onFormStateChange,
+  isSubmitDisabled,
+  onSubmit,
+  onValidationResponse: _onValidationResponse,
+  onSuccess,
+  onError
+}) {
+  const {
+    applyAction: osdkApplyAction,
+    isPending
+  } = useOsdkAction(actionDefinition);
+  const {
+    metadata,
+    loading: metadataLoading,
+    error: metadataError
+  } = useOsdkMetadata(actionDefinition);
+  useEffect(function () {
+    if (metadataError != null) {
+      onError?.({
+        type: "unknown",
+        error: metadataError
+      });
+    }
+  }, [metadataError, onError]);
+  const parameters = metadata?.parameters;
+  const resolvedFieldDefinitions = useMemo(() => formFieldDefinitions ?? (metadata != null ? getDefaultFieldDefinitions(metadata) : EMPTY_FIELD_DEFINITIONS), [formFieldDefinitions, metadata]);
+  const rendererFieldDefinitions = useMemo(() =>
+  // RendererFieldDefinition is a discriminated union keyed by fieldComponent.
+  // TypeScript can't verify that the spread preserves the fieldComponent ↔
+  // fieldComponentProps pairing, but FormFieldDefinition guarantees it.
+  resolvedFieldDefinitions.map(def => ({
+    ...def,
+    fieldKey: String(def.fieldKey),
+    fieldType: parameters?.[String(def.fieldKey)]?.type,
+    defaultValue: def.defaultValue
+  })), [resolvedFieldDefinitions, parameters]);
+  const coerceFormState = useCallback(rawState => {
+    const coerced = {};
+    for (const [key, value] of Object.entries(rawState)) {
+      coerced[key] = coerceFieldValue(parameters?.[key]?.type, value);
+    }
+    return coerced;
+  }, [parameters]);
+  const handleSubmit = useCallback(async rawFormState => {
+    const formState = coerceFormState(rawFormState);
+    try {
+      if (onSubmit != null) {
+        await onSubmit(formState, osdkApplyAction);
+      } else {
+        const result = await osdkApplyAction(formState);
+        onSuccess?.(result);
+      }
+    } catch (e) {
+      onError?.({
+        type: "submission",
+        error: e
+      });
+    }
+  }, [coerceFormState, onSubmit, osdkApplyAction, onSuccess, onError]);
+  const handleFieldValueChange = useCallback((fieldKey, value) => {
+    onFormStateChange?.(prev => ({
+      ...prev,
+      [fieldKey]: value
+    }));
+  }, [onFormStateChange]);
+  const resolvedTitle = formTitle ?? metadata?.displayName ?? actionDefinition.apiName;
+  const commonProps = {
+    formTitle: resolvedTitle,
+    fieldDefinitions: rendererFieldDefinitions,
+    onSubmit: handleSubmit,
+    isSubmitDisabled,
+    isPending,
+    isLoading: metadataLoading,
+    onFieldValueChange: handleFieldValueChange
+  };
+  if (!(controlledFormState != null)) {
+    return /*#__PURE__*/React.createElement(BaseForm, commonProps);
+  }
+  return /*#__PURE__*/React.createElement(BaseForm, _extends({}, commonProps, {
+    formState: controlledFormState
+  }));
+});
+//# sourceMappingURL=ActionForm.js.map