twenty-ui 1.0.0-alpha.2 → 2.42.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## [Unreleased]
+
+### Breaking Changes
+
+- **Public module ownership changes without a deprecation window.** This release removes 55 public React exports and the `twenty-ui/primitives/json-visualizer` entry point. Applications using the removed imports must migrate when upgrading; compatibility exports are not provided.
+- Import shared compositions, including `JsonTree`, menu presets, and Toast components and hooks, from `twenty-ui/components`. Foundational controls retain `twenty-ui/primitives/<family>` imports. The optional code editor retains `twenty-ui/components/code-editor`.
+- Field displays, application links, placeholders, and feature animations are no longer package exports. External applications must own these integrations or compose supported primitives. Internal implementation parts are private.
+- `Info` uses `href` and `render` in place of `to`. Replace `AnimatedEaseInOut` with `AnimatedExpandableContainer`.
+
+Keep `twenty-ui`, `twenty-sdk`, and `twenty-client-sdk` versions aligned when upgrading Twenty apps.

package/README.md

@@ -6,59 +6,76 @@
 
 Twenty's open-source React UI component library: components, icons, and design tokens built on a zero-runtime, CSS-variable styling layer.
 
+Read the [twenty-ui documentation](https://docs.twenty.com/ui/getting-started) for setup, theming, and component guides.
+
+> **Alpha:** `twenty-ui` is still in alpha. Its version number follows the Twenty SDK release cycle. APIs and component behavior may change between releases.
+
+## Upgrading
+
+The next release changes public module ownership and removes exports without a deprecation window. Read the [breaking release notes](./CHANGELOG.md#unreleased) before upgrading.
+
 # Installation
 
+For a standalone React application, install the library and its peer dependencies. React 19 is required.
+
 ```bash
-npm install twenty-ui
+npm install twenty-ui react@^19 react-dom@^19
 ```
 
-`react`, `react-dom`, and `monaco-editor` are peer dependencies (install them in your app). `monaco-editor` is only required if you use the code editor components.
+The code editor is available separately from `twenty-ui/components/code-editor`. Only applications using that entry point need to install its optional peers:
+
+```bash
+npm install @monaco-editor/react monaco-editor
+```
+
+For Twenty apps, follow [Using Twenty UI components](https://docs.twenty.com/developers/extend/apps/layout/front-components#using-twenty-ui-components). The front component renderer supplies the workspace theme. Keep `twenty-ui`, `twenty-sdk`, and `twenty-client-sdk` on the same version.
 
 # Usage
 
-Import the base styles once, pick a theme stylesheet, and wrap your app in `ThemeProvider`:
+For a standalone React application, import the base styles once, pick a theme stylesheet, and wrap your app in `ThemeProvider`:
 
 ```tsx
 import { ThemeProvider } from 'twenty-ui/theme-constants';
-import { Button } from 'twenty-ui/input';
+import { Button } from 'twenty-ui/primitives/input';
 
 import 'twenty-ui/style.css';
 import 'twenty-ui/theme-light.css';
 
 export const App = () => (
   <ThemeProvider colorScheme="light">
-    <Button title="Click me" />
+    <Button>Click me</Button>
   </ThemeProvider>
 );
 ```
 
-Components are available from the root entry point or from a specific subpath for better tree-shaking:
+Prefer the matching subpath for better tree-shaking. Imports from the `twenty-ui` root entry point are also supported.
 
 ```tsx
-import { Button } from 'twenty-ui';
-import { Button } from 'twenty-ui/input';
+import { Button } from 'twenty-ui/primitives/input';
 ```
 
 # Entry points
 
-| Subpath | Contents |
-| --- | --- |
-| `twenty-ui` | All components, icons, theme tokens, and utilities |
-| `twenty-ui/accessibility` | Accessibility helpers |
-| `twenty-ui/assets` | Logos and static assets |
-| `twenty-ui/data-display` | Avatars, chips, tags, and other display components |
-| `twenty-ui/feedback` | Progress bars, loaders, and status feedback |
-| `twenty-ui/icon` | Icon components and the icon provider |
-| `twenty-ui/input` | Buttons, switches, and form inputs |
-| `twenty-ui/json-visualizer` | JSON tree viewer |
-| `twenty-ui/layout` | Layout primitives |
-| `twenty-ui/navigation` | Menus, links, and navigation components |
-| `twenty-ui/surfaces` | Cards, tooltips, and surface components |
-| `twenty-ui/testing` | Storybook and test decorators |
-| `twenty-ui/theme` | Theme types and helpers |
-| `twenty-ui/theme-constants` | Design tokens, `ThemeProvider`, and `useTheme` |
-| `twenty-ui/typography` | Text and typography components |
-| `twenty-ui/utilities` | Hooks and shared utilities |
+| Subpath                              | Contents                                                              |
+| ------------------------------------ | --------------------------------------------------------------------- |
+| `twenty-ui`                          | Components except the code editor, icons, theme tokens, and utilities |
+| `twenty-ui/assets`                   | Logos and static assets                                               |
+| `twenty-ui/components`               | Shared design presets and reusable app building blocks                |
+| `twenty-ui/components/code-editor`   | Code editor, editor header, and editor theme helpers                  |
+| `twenty-ui/icon`                     | Icon components and the icon provider                                 |
+| `twenty-ui/primitives`               | Foundational UI controls and compound controls                        |
+| `twenty-ui/primitives/accessibility` | Hidden elements and keyboard interaction helpers                      |
+| `twenty-ui/primitives/data-display`  | Avatars, chips, tags, color samples, and status indicators            |
+| `twenty-ui/primitives/feedback`      | Banners, progress bars, and loaders                                   |
+| `twenty-ui/primitives/input`         | Buttons and form controls                                             |
+| `twenty-ui/primitives/layout`        | Expansion, separators, direction, and resizing                        |
+| `twenty-ui/primitives/navigation`    | Action links, list items, and tabs                                    |
+| `twenty-ui/primitives/surfaces`      | Cards, dialogs, menus, popovers, and tooltips                         |
+| `twenty-ui/primitives/typography`    | Text and headings                                                     |
+| `twenty-ui/testing`                  | Storybook and test decorators                                         |
+| `twenty-ui/theme`                    | Theme types and helpers                                               |
+| `twenty-ui/theme-constants`          | Design tokens, `ThemeProvider`, and `useTheme`                        |
+| `twenty-ui/utilities`                | Hooks and shared utilities                                            |
 
 # Theming
 
@@ -68,6 +85,22 @@ import { Button } from 'twenty-ui/input';
 
 # Development
 
+Shared component sources live in `src/components/{data-display,feedback,input,layout,navigation,typography}`, with the optional editor in `src/components/code-editor`. Keep each component's types, stories, tests, and private parts beside its implementation. The generated `components` barrel provides the public imports.
+
+Primitive guides belong in `packages/twenty-docs/ui/primitives`. Shared component guides belong in `packages/twenty-docs/ui/components`. For each stateful API that supports both modes, include separate **Uncontrolled state** and **Controlled state** examples with the same scenario, labels, and initial state. Keep each example complete, with public imports and one exported example component.
+
+Explain state ownership before advanced behavior such as indeterminate selection or manual tab activation. Document independent states, such as selection and popup visibility, separately. For components that delegate state to a parent or group, explain that ownership and link to the relevant examples.
+
+For compound components, include an anatomy tree and identify required parts, optional parts, and elements supplied internally. Show supported composition with complete examples, use Twenty UI components for supporting controls, and explain how custom wrappers preserve props and refs. Use `text` fences for structural diagrams and `tsx` fences for runnable examples so the documentation checker validates the examples.
+
+## Internal state
+
+twenty-ui uses Base UI's store for notification state. Each `ToastProvider` creates its own store, and the toaster subscribes to the toast list. Queue rules and rendering remain owned by twenty-ui. Consumers use `useToast()` without configuring a state library.
+
+The store factory and subscription hook are internal to the toast module. `@base-ui/utils` is a direct dependency pinned to the version used by `@base-ui/react`, and the library build keeps it external. Review its store API changes when upgrading the dependency.
+
+## Testing
+
 Component interaction and behavior tests belong in Storybook stories (`*.stories.tsx`) using `play` functions. Component unit tests are reserved for conformance (native props, refs, class names, rendering, and prop types). Keep non-interactive utility, hook, and token tests in the Vitest unit project; avoid duplicating story coverage there.
 
 ```bash
@@ -80,3 +113,13 @@ npx vitest run --root packages/twenty-ui --project unit <file>   # Run a single
 # License
 
 twenty-ui is released under the [MIT](https://github.com/twentyhq/twenty/blob/main/packages/twenty-ui/LICENSE) license.
+
+# Module ownership
+
+Primitives provide foundational interaction and presentation. Shared components compose primitives into reusable presets, pickers, menu rows, notifications, and the JSON viewer. Both layers accept data, labels, and callbacks from their host.
+
+Routing adapters, record formatting, product illustrations, and feature-specific animation belong to `twenty-front`. Implementation parts live in `internal` or `parts` directories and are excluded from published barrels.
+
+Run `node --import tsx scripts/checkModuleOwnership.ts` from this package after changing the public interface. When intentionally adding or removing a public React component, regenerate `docs/module-ownership.json` with `node --import tsx scripts/checkModuleOwnership.ts --write` and review the snapshot diff. CI checks the committed snapshot and the dependency boundaries without updating them.
+
+`twenty-ui/testing` includes routing decorators and requires the optional `react-router-dom` peer. The package check verifies each published entry point, allowing that peer only in testing and the Monaco peers only in `twenty-ui/components/code-editor`.