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

package/index.d.ts

@@ -746,9 +746,14 @@ declare class TiptapFloatingMenuDirective implements OnInit, OnDestroy {
  *
  * Usage:
  * <button #trigger>Open</button>
- * <div [popover]="trigger" [isOpen]="isOpen">
+ * <div [documentEnginePopover]="trigger" [isOpen]="isOpen">
  *   Content
  * </div>
+ *
+ * The host is pinned `position: fixed`, so floating-ui is asked for viewport-
+ * relative coordinates (`strategy: 'fixed'`). Omitting the strategy yields
+ * offset-parent-relative numbers, which are off by the page's scroll offset
+ * once written onto a fixed element.
  */
 declare class PopoverDirective implements OnChanges, AfterViewInit, OnDestroy {
     private elRef;
@@ -756,7 +761,16 @@ declare class PopoverDirective implements OnChanges, AfterViewInit, OnDestroy {
     /**
      * The trigger element reference (ElementRef or HTMLElement)
      */
-    popover: ElementRef<HTMLElement> | HTMLElement;
+    documentEnginePopover?: ElementRef<HTMLElement> | HTMLElement;
+    /**
+     * The trigger element reference (ElementRef or HTMLElement)
+     *
+     * @deprecated Use `documentEnginePopover`. `[popover]` collides with the
+     * native HTML popover attribute and will be removed in the next major.
+     */
+    popover?: ElementRef<HTMLElement> | HTMLElement;
+    /** The trigger, whichever input supplied it. */
+    private get trigger();
     /**
      * Whether the popover is open
      */
@@ -784,9 +798,18 @@ declare class PopoverDirective implements OnChanges, AfterViewInit, OnDestroy {
     private updateVisibility;
     private setupFloating;
     private _setupFloatingInternal;
+    /**
+     * Position `dropdownEl` against `triggerEl`.
+     *
+     * `strategy: 'fixed'` is required: the host binding pins this element to
+     * `position: fixed`, so the coordinates must be viewport-relative. Without it
+     * floating-ui returns offset-parent-relative numbers and the panel lands the
+     * page's scroll offset away from its trigger.
+     */
+    private reposition;
     private cleanup;
     static ɵfac: i0.ɵɵFactoryDeclaration<PopoverDirective, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<PopoverDirective, "[popover]", never, { "popover": { "alias": "popover"; "required": false; }; "isOpen": { "alias": "isOpen"; "required": false; }; "placement": { "alias": "placement"; "required": false; }; "offset": { "alias": "offset"; "required": false; }; "padding": { "alias": "padding"; "required": false; }; }, {}, never, never, true, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<PopoverDirective, "[documentEnginePopover], [popover]", never, { "documentEnginePopover": { "alias": "documentEnginePopover"; "required": false; }; "popover": { "alias": "popover"; "required": false; }; "isOpen": { "alias": "isOpen"; "required": false; }; "placement": { "alias": "placement"; "required": false; }; "offset": { "alias": "offset"; "required": false; }; "padding": { "alias": "padding"; "required": false; }; }, {}, never, never, true, never>;
 }
 
 declare const DocumentEngineKit: Extension<DocumentEngineConfig, any>;
@@ -1277,6 +1300,7 @@ declare class CheckboxComponent implements ControlValueAccessor {
     checked: boolean;
     checkedChange: EventEmitter<boolean>;
     hostClass: boolean;
+    private readonly cdr;
     private onChange;
     private onTouched;
     onCheckboxChange(event: Event): void;
@@ -1711,6 +1735,8 @@ declare class ToolbarBubbleMenuComponent implements AfterViewInit, OnDestroy {
     private currentViewRef;
     private currentViewId;
     private currentAttributes;
+    private cleanupAutoUpdate?;
+    private positionTimeout?;
     isVisible: boolean;
     ngAfterViewInit(): void;
     ngOnDestroy(): void;
@@ -1733,6 +1759,21 @@ declare class ToolbarBubbleMenuComponent implements AfterViewInit, OnDestroy {
     private handleNavigateTo;
     private handleGoBack;
     private findViewConfig;
+    /**
+     * Anchor the bubble to its trigger with floating-ui, matching
+     * `PopoverDirective`.
+     *
+     * The hand-rolled version this replaces measured the trigger exactly once, so
+     * scrolling left the panel welded to the viewport while its target slid away.
+     * It also had no third case: a panel that fit neither below nor above got a
+     * negative `top`, putting its own header off the top edge of the screen.
+     * `flip` handles the second placement and `shift` clamps the panel into the
+     * viewport instead, so there is no unhandled case left.
+     *
+     * `strategy: 'fixed'` matches the `position: fixed` written below — asking for
+     * the default `'absolute'` coordinates would offset the panel by the page's
+     * scroll amount.
+     */
     private positionBubble;
     static ɵfac: i0.ɵɵFactoryDeclaration<ToolbarBubbleMenuComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<ToolbarBubbleMenuComponent, "document-engine-toolbar-bubble-menu", never, { "editor": { "alias": "editor"; "required": false; }; "config": { "alias": "config"; "required": false; }; }, {}, never, never, true, never>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phuong-tran-redoc/document-engine-angular",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "module",
   "license": "MIT",
   "author": "Realestatedoc (Redoc)",
@@ -35,7 +35,7 @@
   "dependencies": {
     "tslib": "^2.3.0",
     "@floating-ui/dom": "^1.7.4",
-    "@phuong-tran-redoc/document-engine-core": "0.1.4"
+    "@phuong-tran-redoc/document-engine-core": "0.1.5"
   },
   "peerDependencies": {
     "rxjs": "^7.5.0",
@@ -75,6 +75,9 @@
     "./styles": {
       "sass": "./src/lib/styles/index.scss"
     },
+    "./styles/tokens": {
+      "sass": "./src/lib/styles/tokens.scss"
+    },
     "./styles/editor-content": {
       "sass": "./src/lib/styles/editor-content.scss"
     },

package/src/lib/styles/_panel-surface.scss

@@ -0,0 +1,43 @@
+/**
+ * Floating-panel surface — the look every bubble menu / popover panel needs to
+ * be legible: an opaque background, a rule, a radius, an elevation and a
+ * stacking order.
+ *
+ * Why this is a mixin and not Tailwind utilities in a template:
+ * utilities like `bg-card`, `border-border` or `shadow-elevation-2` only exist
+ * if the HOST app's `tailwind.config.js` extends its theme with exactly those
+ * keys. The demo app happens to; a consumer with its own theme does not, and
+ * there the class names generate no rule at all — the panel then renders as
+ * transparent text floating over the page. A component library must not put
+ * that requirement on its host, so the panel carries its own surface.
+ *
+ * Every value resolves from a CSS custom property WITH a fallback, so:
+ *   - a consumer that remaps the tokens gets its own theme, and
+ *   - a consumer that remaps nothing still gets a usable, opaque panel.
+ *
+ * Tokens read here (all optional, all documented in docs/THEMING.md):
+ *   --popover / --card                       panel background
+ *   --popover-foreground / --card-foreground panel text
+ *   --border                                 panel rule
+ *   --shadow-elevation-2                     panel elevation
+ */
+
+/* Light-mode floors, used only when the consumer defines nothing. */
+$de-fallback-surface: hsl(0 0% 100%) !default;
+$de-fallback-surface-foreground: hsl(222.2 84% 4.9%) !default;
+$de-fallback-border: hsl(214.3 31.8% 91.4%) !default;
+
+@mixin panel-surface($z-index: 30, $radius: 0.25rem) {
+  box-sizing: border-box;
+  z-index: $z-index;
+  border-radius: $radius;
+  border: 1px solid var(--border, #{$de-fallback-border});
+
+  /* `--popover` is the semantic token for a floating surface; `--card` is the
+   * broader surface token most consumers already define, so it is the second
+   * chance before the hardcoded floor. */
+  background-color: var(--popover, var(--card, #{$de-fallback-surface}));
+  color: var(--popover-foreground, var(--card-foreground, #{$de-fallback-surface-foreground}));
+
+  box-shadow: var(--shadow-elevation-2, 0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px -1px rgba(0, 0, 0, 0.1));
+}

package/src/lib/styles/document-editor.scss

@@ -7,10 +7,31 @@
   color: var(--card-foreground, #000);
   box-shadow: none;
 
+  // Participate in a parent that has a real height (a fixed-height container, a
+  // flex/grid cell) instead of only ever sizing to content. `flex: 1 1 auto` is
+  // what actually claims that height: without it this box stays content-sized as
+  // a flex item of :host, and a fixed-height container is left with a band of
+  // dead, unclickable space under the editable.
+  //
+  // `max-height: 100%` is inert when the parent's height is indefinite (a
+  // percentage against an auto height resolves to none), so an unconstrained
+  // consumer still gets a box that simply grows.
+  flex: 1 1 auto;
+  min-height: 0;
+  max-height: 100%;
+
   &__content {
     padding: 1rem;
     border: 1px solid var(--border, #e5e7eb);
     background-color: var(--card, #fff);
+
+    // Take the leftover space so the editing surface below can stretch into it.
+    // Deliberately no `overflow` here: the panels rendered inside carry selects
+    // and colour popovers, and an overflow ancestor can clip them.
+    display: flex;
+    flex-direction: column;
+    flex: 1 1 auto;
+    min-height: 0;
   }
 }
 
@@ -18,3 +39,43 @@
 // document-engine-toolbar ~ .document-engine-document-editor__content {
 //   border-top: 1px solid var(--border, #e5e7eb);
 // }
+
+/**
+ * Editing-surface sizing.
+ *
+ * The library used to size the contenteditable to its content and nothing else,
+ * so an emptied editor collapsed to a single line. In a fixed-height container
+ * that left a ~28px editable inside a ~480px box that plainly looks like a text
+ * field, and clicking anywhere but that one line did nothing.
+ *
+ * Two hooks, one rule:
+ *   - `--de-editor-min-height` is the floor (default `12rem`). Remap it, or set
+ *     it to `0` to opt out entirely.
+ *   - `flex: 1 1 auto` lets an ancestor with a real height drive the surface, so
+ *     the editable fills a fixed-height container without any magic number.
+ *
+ * `.tiptap-editor` is the class `TiptapEditorDirective` puts on its host;
+ * `.tiptap` / `.ProseMirror` is the contenteditable Tiptap creates inside it.
+ */
+.tiptap-editor {
+  display: flex;
+  flex-direction: column;
+  flex: 1 1 auto;
+  min-height: 0;
+
+  // The editing surface is the scroll container. Without this, `max-height: 100%`
+  // above caps the wrapper while nothing scrolls, so a long document paints
+  // straight through the bottom of a fixed-height container and over whatever
+  // follows it on the page.
+  //
+  // Safe to put overflow here: the floating panels are rendered inside
+  // `document-engine-toolbar`, a sibling of the content box, never a descendant
+  // of this element — so there is nothing of theirs for this to clip.
+  overflow-y: auto;
+
+  > .tiptap,
+  > .ProseMirror {
+    flex: 1 1 auto;
+    min-height: var(--de-editor-min-height, 12rem);
+  }
+}

package/src/lib/styles/index.scss

@@ -23,8 +23,16 @@
  *
  * All styles use class/element selectors and CSS-variable-driven values, so you
  * can also override them with your own CSS without importing these files.
+ *
+ * Theming: this barrel also ships zero-specificity DEFAULTS for every custom
+ * property the library reads (`_tokens.scss`, emitted on `:where(:root)`), so it
+ * looks right out of the box and any token you declare yourself wins without a
+ * specificity fight. The full list is in `docs/THEMING.md`.
  */
 
+// Token defaults first, so they sit at the top of the emitted sheet.
+@use 'tokens';
+
 @forward 'icon';
 @forward 'button';
 @forward 'toolbar';

package/src/lib/styles/tokens.scss

@@ -0,0 +1,69 @@
+/**
+ * Default values for every CSS custom property the library's CSS reads.
+ *
+ * The library's stylesheets are token-driven: they paint with `var(--border)`,
+ * `var(--popover)`, `var(--foreground)` and friends. Historically the library
+ * *consumed* those tokens without ever defining or documenting them, so a
+ * consumer that had not happened to declare the same shadcn-style token set got
+ * panels with no background and text with no colour.
+ *
+ * This file closes that hole: it declares a light-mode default for every token,
+ * so importing the chrome barrel is enough to get a working look with zero
+ * theming. See `docs/THEMING.md` for the full contract.
+ *
+ * ## Why `:where(:root)`
+ *
+ * `:where()` contributes **zero specificity**, so ANY declaration a consumer
+ * writes — `:root { --border: … }`, `.dark { --border: … }`, an inline style,
+ * a `[data-theme]` block — beats these defaults regardless of source order.
+ * They are a floor, never a fight.
+ *
+ * ## Rescoping
+ *
+ * The defaults are also exposed as a mixin, so you can plant a fresh set on any
+ * container — e.g. an embedded editor that must ignore the surrounding theme:
+ *
+ *   @use '@phuong-tran-redoc/document-engine-angular/styles/tokens' as de-tokens;
+ *   .my-isolated-editor { @include de-tokens.token-defaults; }
+ */
+
+@mixin token-defaults {
+  /* --- Surfaces --- */
+  --background: hsl(0 0% 100%);
+  --foreground: hsl(222.2 84% 4.9%);
+  --card: hsl(0 0% 100%);
+  --card-foreground: hsl(222.2 84% 4.9%);
+  --popover: hsl(0 0% 100%);
+  --popover-foreground: hsl(222.2 84% 4.9%);
+
+  /* --- Accents & state --- */
+  --primary: hsl(222.2 47.4% 11.2%);
+  --primary-foreground: hsl(210 40% 98%);
+  --secondary: hsl(210 40% 96.1%);
+  --secondary-foreground: hsl(222.2 47.4% 11.2%);
+  --muted: hsl(210 40% 96.1%);
+  --muted-foreground: hsl(215.4 16.3% 46.9%);
+  --accent: hsl(210 40% 96.1%);
+  --accent-foreground: hsl(222.2 47.4% 11.2%);
+  --destructive: hsl(0 84.2% 60.2%);
+  --destructive-foreground: hsl(210 40% 98%);
+
+  /* --- Lines --- */
+  --border: hsl(214.3 31.8% 91.4%);
+  --input: hsl(214.3 31.8% 91.4%);
+  --ring: hsl(222.2 84% 4.9%);
+
+  /* --- Elevation ---
+   * Consumed by panels, dropdowns and inputs. Undefined, `box-shadow: var(…)`
+   * resolves to nothing, which is how floating panels lost their elevation. */
+  --shadow-elevation-1: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
+  --shadow-elevation-2: 0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px -1px rgba(0, 0, 0, 0.1);
+  --shadow-elevation-3: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1);
+
+  /* --- Editing surface sizing (see docs/THEMING.md#sizing) --- */
+  --de-editor-min-height: 12rem;
+}
+
+:where(:root) {
+  @include token-defaults;
+}