@phuong-tran-redoc/document-engine-angular 0.1.4 → 0.1.6

package/README.md

@@ -50,9 +50,13 @@ Add the SCSS entry to your global styles (or `angular.json` styles array):
 
 ```scss
 // styles.scss
-@import '@phuong-tran-redoc/document-engine-angular/styles';
+@use '@phuong-tran-redoc/document-engine-angular/styles';
 ```
 
+That one import is the whole baseline — it ships the editor chrome **and** a default value for every
+design token the library reads, so it looks right with no theming at all. **Tailwind CSS is not
+required**; the library does not depend on your Tailwind config.
+
 ---
 
 ## 🚀 Quick Start
@@ -167,11 +171,49 @@ The feature-toggle object passed to `[config]`. Each key is a boolean or an opti
 
 > The package entry `index.ts` is the public contract — additive changes only between minor versions.
 
----
+### Deprecations
+
+| Deprecated | Use instead | Removed in |
+| --- | --- | --- |
+| `[popover]` selector/input on `PopoverDirective` | `[documentEnginePopover]` | next major |
+
+`[popover]` still works, so no consumer breaks on upgrade. It is being retired because it collides with
+the platform's native [`popover`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/popover)
+HTML attribute — an element carrying both gets the browser's top-layer behaviour *and* ours.
 
-## 🎨 Styling
+```html
+<!-- before -->
+<div [popover]="triggerRef">…</div>
+<!-- after -->
+<div [documentEnginePopover]="triggerRef">…</div>
+```
+
+---
 
-Import the SCSS entry (see [Installation](#importing-styles)). The editor ships a Tailwind + SCSS design system; theme it through your global stylesheet alongside your app's design tokens.
+## 🎨 Styling & theming
+
+Import the SCSS entry (see [Importing Styles](#importing-styles)), then theme by **redeclaring CSS
+custom properties** — never by overriding rule bodies.
+
+**[`docs/THEMING.md`](https://github.com/phuong-tran-redoc/document-engine/blob/main/docs/THEMING.md) is
+the contract.** It lists every token the library reads
+(colour, elevation, sizing), its default, and what it paints. Highlights:
+
+- The barrel's defaults are emitted on `:where(:root)`, which has **zero specificity** — anything you
+  declare (`:root`, `.dark`, `[data-theme]`, an inline style) wins regardless of source order. No
+  `!important`, no matching a selector shape.
+- Dark mode is purely a matter of redeclaring the tokens on your dark selector; nothing in the library
+  hardcodes a colour.
+- `--de-editor-min-height` (default `12rem`) sets the editing surface's floor; alternatively give the
+  `document-engine-editor` element a real height and the surface fills it.
+- **The editing surface does not scroll internally — it grows, and the page scrolls.** `0.1.5` briefly
+  made it a scroll container; that was reverted in `0.1.6` because the selection bubble menu is an
+  absolutely-positioned descendant of it, so the scroller became the panel's clip rect and a dropdown
+  opening upward lost its top options to the clip. If you need a fixed-height box that scrolls its
+  content, put `overflow: auto` on **your own** wrapper around `document-engine-editor`, never on
+  `.tiptap-editor`.
+- Prose and editing-affordance styles are **opt-in** subpaths (`styles/editor-content`,
+  `styles/editor-interaction`), so the baseline can never impose a look on your documents.
 
 ---