@osdk/react-components 0.2.0-beta.9 → 0.2.1-main-20260407074313

package/AGENTS.md

@@ -0,0 +1,26 @@
+# @osdk/react-components
+
+Pre-built, Ontology-aware React components. Pass in OSDK entities and they handle data loading, caching, and state management automatically. Requires `@osdk/react` (see the `@osdk/react` package's `AGENTS.md` for hooks and provider setup).
+
+## Components
+
+All components import from `@osdk/react-components/experimental`.
+
+| Component              | Description                                                                                                                                 |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| **ObjectTable**        | Table for displaying OSDK object sets with sorting, filtering, inline editing, column pinning/resizing, row selection, and infinite scroll. |
+| **BaseTable**          | OSDK-agnostic base table — use when building custom data fetching on top of the table UI.                                                   |
+| **FilterList**         | Aggregation-based filter UI for object sets with draggable reordering.                                                                      |
+| **BaseFilterList**     | OSDK-agnostic base filter list — use for custom filter implementations.                                                                     |
+| **ColumnConfigDialog** | Dialog for managing column visibility and drag-and-drop reordering.                                                                         |
+| **PdfViewer**          | PDF viewer for OSDK Media objects with toolbar, search, annotations, sidebar (thumbnails/outline), highlight mode, and form fields.         |
+| **BasePdfViewer**      | OSDK-agnostic base PDF viewer — accepts a URL or ArrayBuffer directly. Use when building custom data fetching on top of the viewer UI.      |
+
+## Documentation
+
+Before using any component, read the relevant doc:
+
+- **Setup & installation**: Read [README.md](https://github.com/palantir/osdk-ts/blob/main/packages/react-components/README.md) for provider, CSS layers, and peer dependencies
+- **ObjectTable**: Read [docs/ObjectTable.md](https://github.com/palantir/osdk-ts/blob/main/packages/react-components/docs/ObjectTable.md) for props, column definitions, examples, theming, and troubleshooting
+- **PdfViewer**: Read [docs/PdfViewer.md](https://github.com/palantir/osdk-ts/blob/main/packages/react-components/docs/PdfViewer.md) for props, annotations, building blocks, hooks, examples, and theming
+- **FilterList**: Read [docs/FilterList.md](https://github.com/palantir/osdk-ts/blob/main/packages/react-components/docs/FilterList.md) for props, examples, and usage

package/CHANGELOG.md

@@ -1,5 +1,361 @@
 # @osdk/react-components
 
+## 0.2.1-main-20260407074313
+
+### Patch Changes
+
+- 79b001e: Add FilePickerField component for attachment and media reference form fields
+- Updated dependencies [bcf359f]
+- Updated dependencies [51ccca8]
+  - @osdk/client@2.8.1-main-20260407074313
+  - @osdk/react@0.10.1-main-20260407074313
+  - @osdk/api@2.8.1-main-20260407074313
+
+## 0.2.0
+
+### Minor Changes
+
+- ce949bd: Simulated release
+- 9f76365: Follow-up cleanups from ActionForm PR
+- 9720083: Add AGENTS.md files for AI IDE context
+- 813f4cb: Add DatetimePickerField component
+- fffbb68: Add DropdownField component with searchable combobox and multi-select support
+- d4ac875: Add text highlight annotation mode to PdfViewer with toolbar toggle button, `onTextHighlight` callback, and multi-rect annotation support via `rects` field on `PdfAnnotation`
+- 8eea31b: feat(pdf): pdf viewer recipes + fixed for form fields
+- 993c023: ObjectTable supports objectSet input
+- 32c27d7: Added useOsdkFunctions to @osdk/react to execute multiple functions in parallel. This is used by ObjectTable to fetch function-backed columns
+- 7080b01: Add base form layout with header, footer, field components, and CSS token variables for theming
+- b4bf087: add complex and aggregation filter input components
+- 02a095b: Support select all in controlled mode
+- dbbfb6f: Add experimental ActionForm component with field renderers, form state hook, and tests
+- e19ff03: Add TextAreaField component using @base-ui Input with render prop for native textarea rendering
+- 4ad9b36: Add NumberInputField component
+- c3da451: add marking button, category group, and validation components for CBAC picker
+- c35231f: add cbac css tokens and create cbac-components package
+- 3eaf3f5: Add CSS layers documentation and Tailwind CSS v4 setup instructions to READMEs
+- 073a5b1: Add ESLint rules for code quality, React best practices, and JSX accessibility
+- 9ff2eca: Add function-backed column query
+- 6516ff9: Fix multiple setData calls
+- 06095fa: Restructure FilterList into base and osdk layers
+- aa908e4: Redesign filter list collapse into separate render tree and simplify header layout
+- 3f4fb81: Address design review and PR review feedback for filter list: exclude strikethrough only on selected items, remove hover-to-show exclude row, fix 3-dots toggle close behavior, remove OR filter operator mode, and various UI polish
+- f6649a5: add collapsible panel, select all, include/exclude toggle, per-item colors, histogram display modes, and session persistence support to filter list
+- e4840fa: Add exclude dropdown, in-filter search, hover-reveal actions, remove button to filter list items, thread objectSet through aggregation hooks so prefiltered sets are respected, and add FilterList storybook stories and documentation
+- 08b979a: Thread objectSet through filter aggregation hooks and add FilterList documentation
+- 7542c11: add remove button to filter list items and memoize dnd accessibility props
+- bc46400: Add skeleton loading states and polish checkbox list, histogram, and range filter inputs
+- d6c2c8b: Fix FilterList styling
+- 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
+- 9893b41: Add storybook
+- 82573b8: Pin react-day-picker to 9.1.0
+- dffac63: Fix styling nits
+- d6c2c8b: Fix FilterList dropdown
+- 7347abe: Update README
+- 66b7125: Add RadioButtonsField component for action form radio button inputs
+- 1135a27: Update Blueprint css import
+- 7a3c43d: feat(pdf): pdf-viewer component
+- 0bf4c53: add e2e sandbox filter list demos and remove unused filter types
+- a198fc5: Fix header cell not aligned
+- 532d0d7: Fix lint errors
+- 074a754: Display function-backed column
+- 6ec2110: Add CustomField component for user-defined field renderers in ActionForm
+- 727fd0e: fix dual @types/react version mismatch
+- 76ee40a: Fix column resize and value change ux
+- 447e29d: Update editable table UX and API to pass the entire row data on edit
+- 6019278: auto-compute peer dependency ranges from changelog history for react and react-components
+- 4c7884f: Add custom column, multi column sort and column config
+- 4ffe6f5: add filter list state management and where clause builder
+- dba18e0: Fix css build
+- b373588: Styling fix with global border-box
+- 52b70aa: Fix onRowClick triggered on row selection
+- 525f277: add filter-list base containers, simple input components, and switch base component
+- 35f2f1a: Add Media inputs/outputs for Queries
+- 05618c3: Add validation state to editable cell
+- fb9383c: Fix table crashes on remount
+- 5f52808: fix(pdf): fix issue with pdf viewer worker import
+- 00677eb: Upgrade Storybook to v10 and add MCP addon.
+- 336a013: refactor(pdf): rename BasePdfRenderer/PdfRenderer to BasePdfViewer/PdfViewer, rename downloadEnabled to enableDownload, expose internal hooks, add onDownload result callback for download success/failure
+- 5ad3ba1: Fix conflicting dependencies and add docs
+- edbe438: FilterList base components with drag-and-drop sorting and tokenized styling
+- 07a6fdb: use SkeletonBar component in table loading cells instead of inline skeleton divs
+- 4187b2b: Fix shift click to select from last selected and header menu styles
+- 9c54ee5: Support editable cell
+
+## 0.2.0-beta.29
+
+### Minor Changes
+
+- 4ad9b36: Add NumberInputField component
+- d6c2c8b: Fix FilterList styling
+- d6c2c8b: Fix FilterList dropdown
+
+## 0.2.0-beta.28
+
+### Minor Changes
+
+- 3eaf3f5: Add CSS layers documentation and Tailwind CSS v4 setup instructions to READMEs
+- 3f4fb81: Address design review and PR review feedback for filter list: exclude strikethrough only on selected items, remove hover-to-show exclude row, fix 3-dots toggle close behavior, remove OR filter operator mode, and various UI polish
+
+## 0.2.0-beta.27
+
+### Minor Changes
+
+- 32c27d7: Added useOsdkFunctions to @osdk/react to execute multiple functions in parallel. This is used by ObjectTable to fetch function-backed columns
+- 6019278: auto-compute peer dependency ranges from changelog history for react and react-components
+
+## 0.2.0-beta.26
+
+### Minor Changes
+
+- 8eea31b: feat(pdf): pdf viewer recipes + fixed for form fields
+- c3da451: add marking button, category group, and validation components for CBAC picker
+- 073a5b1: Add ESLint rules for code quality, React best practices, and JSX accessibility
+- 82573b8: Pin react-day-picker to 9.1.0
+- 66b7125: Add RadioButtonsField component for action form radio button inputs
+- 6ec2110: Add CustomField component for user-defined field renderers in ActionForm
+
+### Patch Changes
+
+- Updated dependencies [520398c]
+- Updated dependencies [ffc6efe]
+- Updated dependencies [4a856cb]
+- Updated dependencies [b0930e4]
+  - @osdk/client@2.8.0-beta.29
+  - @osdk/api@2.8.0-beta.29
+  - @osdk/react@0.10.0-beta.14
+
+## 0.2.0-beta.25
+
+### Minor Changes
+
+- d4ac875: Add text highlight annotation mode to PdfViewer with toolbar toggle button, `onTextHighlight` callback, and multi-rect annotation support via `rects` field on `PdfAnnotation`
+- e19ff03: Add TextAreaField component using @base-ui Input with render prop for native textarea rendering
+
+### Patch Changes
+
+- Updated dependencies [f294f5a]
+- Updated dependencies [2855223]
+- Updated dependencies [d284bf2]
+- Updated dependencies [b68cebd]
+  - @osdk/client@2.8.0-beta.28
+  - @osdk/react@0.10.0-beta.13
+  - @osdk/api@2.8.0-beta.28
+
+## 0.2.0-beta.24
+
+### Minor Changes
+
+- 813f4cb: Add DatetimePickerField component
+- e4840fa: Add exclude dropdown, in-filter search, hover-reveal actions, remove button to filter list items, thread objectSet through aggregation hooks so prefiltered sets are respected, and add FilterList storybook stories and documentation
+
+### Patch Changes
+
+- Updated dependencies [46dfbec]
+  - @osdk/react@0.10.0-beta.12
+
+## 0.2.0-beta.23
+
+### Minor Changes
+
+- c35231f: add cbac css tokens and create cbac-components package
+- 5f52808: fix(pdf): fix issue with pdf viewer worker import
+- 336a013: refactor(pdf): rename BasePdfRenderer/PdfRenderer to BasePdfViewer/PdfViewer, rename downloadEnabled to enableDownload, expose internal hooks, add onDownload result callback for download success/failure
+- 07a6fdb: use SkeletonBar component in table loading cells instead of inline skeleton divs
+
+### Patch Changes
+
+- Updated dependencies [fceb4ce]
+  - @osdk/client@2.8.0-beta.27
+  - @osdk/api@2.8.0-beta.27
+  - @osdk/react@0.10.0-beta.11
+
+## 0.2.0-beta.22
+
+### Minor Changes
+
+- 7080b01: Add base form layout with header, footer, field components, and CSS token variables for theming
+- 08b979a: Thread objectSet through filter aggregation hooks and add FilterList documentation
+- dffac63: Fix styling nits
+- b373588: Styling fix with global border-box
+
+### Patch Changes
+
+- Updated dependencies [b1e8bba]
+- Updated dependencies [599426b]
+- Updated dependencies [60b5ffb]
+- Updated dependencies [61e33ab]
+  - @osdk/react@0.10.0-beta.11
+  - @osdk/client@2.8.0-beta.26
+  - @osdk/api@2.8.0-beta.26
+
+## 0.2.0-beta.21
+
+### Minor Changes
+
+- fffbb68: Add DropdownField component with searchable combobox and multi-select support
+
+### Patch Changes
+
+- @osdk/api@2.8.0-beta.24
+- @osdk/client@2.8.0-beta.24
+- @osdk/react@0.10.0-beta.10
+
+## 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

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:**
@@ -51,7 +53,49 @@ function App() {
 
 ### CSS Setup
 
-Add this to your application's entry css file (e.g., `index.css` or `index.scss`):
+Add the OSDK style imports to your application's entry CSS file (e.g., `index.css`).
+
+#### Understanding CSS Layers
+
+OSDK uses CSS [`@layer`](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer) to make theming predictable. If you're not familiar with `@layer`, here's what you need to know:
+
+**What is `@layer`?** CSS `@layer` lets you group styles into named layers and control the order in which they apply. When two styles target the same element, the style in the _later_ layer always wins — regardless of selector specificity. This is what makes the theming system maintainable.
+
+**OSDK's layers:**
+
+| Layer             | Purpose                                                    |
+| ----------------- | ---------------------------------------------------------- |
+| `osdk.tokens`     | Design tokens (colors, spacing, typography) — the defaults |
+| `osdk.components` | Component structural styles (layout, borders, sizing)      |
+
+Because `osdk.components` is declared after `osdk.tokens`, component styles take priority over token defaults when they overlap.
+
+**Adding your own layer:** You can add a custom layer (e.g., `user.brand`) after the OSDK layers to override any token or component style. Later layers always win.
+
+**When styles conflict, CSS resolves them in this order:**
+
+1. **Layer order** — Later layers always win (`user.brand` > `osdk.components` > `osdk.tokens`)
+2. **Selector specificity** — More specific selectors win _within the same layer_
+3. **Source order** — Later declarations win when specificity is equal
+
+#### With Tailwind CSS v4
+
+> **Important:** The `@layer` declaration defines the cascade order. Wrapping the Tailwind import in `layer(tailwind)` nests all of Tailwind's styles into a single named layer. By listing `tailwind` before the OSDK layers, OSDK styles take priority over Tailwind's resets and utilities.
+
+```css
+/* index.css */
+@layer tailwind, osdk.tokens, osdk.components, user.brand;
+
+@import "tailwindcss" layer(tailwind);
+
+@import "@osdk/react-components-styles" layer(osdk.tokens);
+@import "@osdk/react-components/styles.css" layer(osdk.components);
+
+/* To add your own brand overrides on top, append a custom layer: */
+@import "./user-brand.css" layer(user.brand);
+```
+
+#### Without Tailwind CSS
 
 ```css
 /* index.css */
@@ -59,7 +103,22 @@ Add this to your application's entry css file (e.g., `index.css` or `index.scss`
 
 @import "@osdk/react-components-styles" layer(osdk.tokens);
 @import "@osdk/react-components/styles.css" layer(osdk.components);
+```
+
+To add your own brand overrides on top:
+
+```css
+/* index.css */
+@layer osdk.tokens, osdk.components, user.brand;
+
+@import "@osdk/react-components-styles" layer(osdk.tokens);
+@import "@osdk/react-components/styles.css" layer(osdk.components);
+@import "./user-brand.css" layer(user.brand);
+```
+
+#### Portal isolation (required)
 
+```css
 .root {
   isolation: isolate;
 }
@@ -67,8 +126,6 @@ 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.
@@ -77,10 +134,112 @@ The components that this package will provide are:
 
 | Component     | Description                                                                        | Documentation                  |
 | ------------- | ---------------------------------------------------------------------------------- | ------------------------------ |
-| `ObjectTable` | Displays an Object Set as a sortable, paginated table                              | [Guide](./docs/ObjectTable.md) |
-| `FilterList`  | Visualize a high-level summary of objects data to allow users to filter that data. | -                              |
+| `ObjectTable` | Displays an Object Set as a sortable, paginated table with inline editing support  | [Guide](./docs/ObjectTable.md) |
+| `PdfViewer`   | Renders PDF documents with annotations, search, sidebar navigation, and zoom       | [Guide](./docs/PdfViewer.md)   |
+| `FilterList`  | Visualize a high-level summary of objects data to allow users to filter that data. | [Guide](./docs/FilterList.md)  |
 | `ActionForm`  | Auto-generated form for executing Ontology Actions                                 | -                              |
 
+## Component Architecture
+
+This package follows a layered architecture pattern to maximize flexibility and reusability.
+
+### Core layers (all components)
+
+1. **OSDK Component Layer** (e.g., `ObjectTable`, `PdfViewer`)
+   - 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`, `BasePdfViewer`)
+   - 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
+
+### Building blocks (select components)
+
+Some components also provide a **building blocks** tier — individual sub-components and hooks that can be composed into fully custom layouts. Not every component needs this; it's offered where the UI is complex enough that users may want to rearrange or replace parts of it.
+
+For example, the PDF viewer offers three levels of customization:
+
+| Tier            | What you use                                                     | What you get                                                     |
+| --------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------- |
+| Drop-in         | `PdfViewer` / `BasePdfViewer`                                    | Full viewer with toolbar, sidebar, search — zero assembly        |
+| Building blocks | `PdfViewerToolbar`, `PdfViewerSidebar`, `PdfViewerContent`, etc. | Custom layout using standard parts                               |
+| Hooks           | `usePdfViewerState` / `usePdfViewerCore` / primitive hooks       | Build entirely custom components; hooks do all the heavy lifting |
+
+See the [PdfViewer guide](./docs/PdfViewer.md) for the full API reference.
+
+### 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. For complex components, consider a building blocks tier with sub-components and hooks
+5. Document all 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
 
 See `@osdk/react-components-styles` README on how to apply custom themes and styling to the components.
@@ -91,7 +250,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 (