@lalternative/editor 0.6.1 → 0.8.0

package/dist/editor.css

@@ -29,30 +29,56 @@
   }
 }
 
-/* Docked to the bottom of the screen by default, floating beside the selection
-   only where there is a pointer and room for it.
+/* A pill above the keyboard by default, floating beside the selection only
+   where there is a pointer and room for it.
 
-   A bar floating next to a selection is the worst place for it on a phone: the
-   finger that made the selection covers it, and iOS draws its own callout in
-   the same spot. Bottom-docked also puts it in thumb reach — and unlike a
-   floating bar, it cannot be pushed off-screen by a selection near an edge. */
+   Near the selection is the worst place for it on a phone: the finger that
+   made the selection covers it, and iOS draws its own callout in the same
+   spot. Sitting above the keyboard puts it in thumb reach instead, and unlike
+   a floating bar it cannot be pushed off-screen by a selection near an edge.
+
+   Shaped as a pill rather than a full-width bar, which is the form the
+   platform already uses for a selection: it reads as something hovering over
+   the document rather than as a piece of the page's chrome, and its rounded
+   ends keep the text either side of it visible.
+
+   Lifted by whatever covers the bottom of the layout viewport: the on-screen
+   keyboard hides the bar without shrinking that viewport, so `bottom: 0` alone
+   parks it under the keys. The component measures the strip and sets the
+   variable; it is 0 whenever nothing covers anything. */
 .lalt-toolbar {
   position: fixed;
-  left: 0;
-  right: 0;
-  bottom: 0;
+  left: 0.5rem;
+  right: 0.5rem;
+  bottom: calc(var(--lalt-keyboard-inset, 0px) + 0.5rem);
   z-index: 100;
   display: flex;
   align-items: center;
-  gap: 0.25rem;
-  padding: 0.5rem;
-  padding-bottom: max(0.5rem, env(safe-area-inset-bottom));
+  justify-content: center;
+  gap: 0.125rem;
+  width: fit-content;
+  max-width: calc(100% - 1rem);
+  margin: 0 auto;
+  margin-bottom: env(safe-area-inset-bottom);
+  padding: 0.25rem;
+  border-radius: 999px;
   background: var(--lalt-editor-surface, #ffffff);
-  border-top: 1px solid var(--lalt-editor-border, rgb(0 0 0 / 0.1));
-  box-shadow: 0 -4px 24px rgb(0 0 0 / 0.18);
+  border: 1px solid var(--lalt-editor-border, rgb(0 0 0 / 0.1));
+  box-shadow:
+    0 6px 20px rgb(0 0 0 / 0.18),
+    0 1px 3px rgb(0 0 0 / 0.1);
   color: var(--lalt-editor-text, #111827);
   user-select: none;
+  /* A long row scrolls rather than stretching the pill past the screen. This
+     clips vertically too — `overflow-y: visible` beside it is ignored by the
+     spec — so the format menu is positioned against the viewport instead of
+     inside this box, and escapes the clip that way. */
   overflow-x: auto;
+  scrollbar-width: none;
+}
+
+.lalt-toolbar::-webkit-scrollbar {
+  display: none;
 }
 
 @media (hover: hover) and (pointer: fine) {
@@ -61,11 +87,9 @@
     top: var(--lalt-toolbar-top, 0);
     right: auto;
     bottom: auto;
-    gap: 0.25rem;
-    padding: 0.25rem;
-    padding-bottom: 0.25rem;
-    border: 1px solid var(--lalt-editor-border, rgb(0 0 0 / 0.1));
-    border-radius: 0.5rem;
+    max-width: none;
+    margin: 0;
+    padding: 0.1875rem;
     /* Deep enough to read as floating over the text rather than sitting in
        it — the bar appears mid-paragraph, with prose on every side. */
     box-shadow:
@@ -75,35 +99,50 @@
   }
 }
 
+/* Transparent by default: inside a pill the buttons are read as a row by the
+   separators between them, and a filled rectangle each would turn the bar into
+   a strip of chips. The fill is what pressing one looks like. */
 .lalt-toolbar__button {
   display: inline-flex;
   align-items: center;
   justify-content: center;
   gap: 0.375rem;
-  /* 44px: what a finger needs. Shrinks to a compact control only where a
-     pointer is doing the aiming. */
-  min-height: 2.75rem;
-  padding: 0.5rem 0.75rem;
-  border-radius: 0.375rem;
-  background: var(--lalt-editor-hover, rgb(0 0 0 / 0.06));
+  /* 40px tall inside a 44px pill: still the target a finger needs, once the
+     bar's own padding is counted. */
+  min-height: 2.5rem;
+  padding: 0.5rem 0.875rem;
+  border-radius: 999px;
+  background: none;
   border: none;
   font: inherit;
-  font-size: 0.875rem;
+  font-size: 0.9375rem;
   font-weight: 500;
   white-space: nowrap;
   cursor: pointer;
   color: inherit;
 }
 
+/* A hairline between actions, the way the platform's own callout separates
+   Copy from Look Up — cheaper than a box around each. */
+.lalt-toolbar > * + * > .lalt-toolbar__button,
+.lalt-toolbar > .lalt-toolbar__button + .lalt-toolbar__button {
+  box-shadow: inset 1px 0 0 var(--lalt-editor-border, rgb(0 0 0 / 0.1));
+}
+
+.lalt-toolbar__button:active {
+  background: var(--lalt-editor-active, rgb(0 0 0 / 0.12));
+}
+
 @media (hover: hover) and (pointer: fine) {
   .lalt-toolbar__button {
     min-height: 0;
-    padding: 0.25rem 0.5rem;
+    padding: 0.3125rem 0.625rem;
+    font-size: 0.875rem;
   }
 }
 
 .lalt-toolbar__button:hover {
-  background: var(--lalt-editor-active, rgb(0 0 0 / 0.12));
+  background: var(--lalt-editor-hover, rgb(0 0 0 / 0.06));
 }
 
 /* The format trigger opens a menu; the caret is what says so. */
@@ -121,19 +160,25 @@
   position: relative;
 }
 
-/* Opens upward from a bottom-docked bar, full width: a menu anchored below it
-   would open off the bottom of the screen. */
+/* Opens upward from the pill: a menu anchored below it would open off the
+   bottom of the screen, or into the keyboard. Card-shaped rather than
+   full-bleed, so it reads as belonging to the bar it grew out of. */
 .lalt-toolbar__menu {
   position: fixed;
-  left: 0;
-  right: 0;
-  bottom: 100%;
-  max-height: 60vh;
+  left: 50%;
+  bottom: calc(var(--lalt-keyboard-inset, 0px) + env(safe-area-inset-bottom) + 3.75rem);
+  transform: translateX(-50%);
+  min-width: 12rem;
+  max-width: calc(100vw - 2rem);
+  max-height: 50vh;
   overflow-y: auto;
   padding: 0.25rem;
   background: var(--lalt-editor-surface, #ffffff);
-  border-top: 1px solid var(--lalt-editor-border, rgb(0 0 0 / 0.1));
-  box-shadow: 0 -8px 24px rgb(0 0 0 / 0.16);
+  border: 1px solid var(--lalt-editor-border, rgb(0 0 0 / 0.1));
+  border-radius: 0.875rem;
+  box-shadow:
+    0 8px 24px rgb(0 0 0 / 0.18),
+    0 1px 3px rgb(0 0 0 / 0.1);
   color: var(--lalt-editor-text, #111827);
 }
 
@@ -144,9 +189,10 @@
     right: 0;
     bottom: auto;
     top: calc(100% + 0.375rem);
+    transform: none;
     min-width: 14rem;
-    border: 1px solid var(--lalt-editor-border, rgb(0 0 0 / 0.1));
-    border-radius: 0.5rem;
+    max-width: none;
+    border-radius: 0.625rem;
     box-shadow: 0 8px 24px rgb(0 0 0 / 0.16);
   }
 }
@@ -159,7 +205,7 @@
   width: 100%;
   min-height: 2.75rem;
   padding: 0.5rem 0.75rem;
-  border-radius: 0.375rem;
+  border-radius: 0.625rem;
   background: none;
   border: none;
   font: inherit;
@@ -280,3 +326,255 @@
 .lalt-suggestion__action:hover {
   background: var(--lalt-editor-hover, rgb(0 0 0 / 0.06));
 }
+
+/* The `/` menu, anchored to the caret by the extension and painted here.
+
+   Fixed to the viewport rather than positioned in the document: the menu is
+   appended to the body so an editor inside an `overflow: hidden` pane cannot
+   clip it. */
+.lalt-slash-anchor {
+  position: fixed;
+  z-index: 10000;
+}
+
+.lalt-slash {
+  min-width: 16rem;
+  max-width: min(20rem, calc(100vw - 1.5rem));
+  overflow: hidden;
+  border: 1px solid var(--lalt-editor-border);
+  border-radius: 0.5rem;
+  background: var(--lalt-editor-surface);
+  color: var(--lalt-editor-text);
+  box-shadow: 0 10px 20px rgb(0 0 0 / 0.12);
+}
+
+.lalt-slash--empty {
+  padding: 0.5rem 0.75rem;
+  font-size: 0.75rem;
+  opacity: 0.6;
+}
+
+.lalt-slash__item {
+  display: flex;
+  align-items: center;
+  gap: 0.625rem;
+  width: 100%;
+  padding: 0.5rem 0.75rem;
+  border: 0;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  font-size: 0.8125rem;
+  text-align: left;
+  cursor: pointer;
+}
+
+/* Room for a thumb where there is no pointer to aim with. */
+@media not (hover: hover), (pointer: coarse) {
+  .lalt-slash__item {
+    padding: 0.6875rem 0.75rem;
+  }
+}
+
+.lalt-slash__item--active,
+.lalt-slash__item:hover {
+  background: var(--lalt-editor-hover);
+}
+
+.lalt-slash__icon {
+  display: flex;
+  flex-shrink: 0;
+  opacity: 0.55;
+}
+
+.lalt-slash__text {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  flex: 1;
+}
+
+.lalt-slash__title {
+  font-weight: 500;
+  line-height: 1.25;
+}
+
+.lalt-slash__description {
+  overflow: hidden;
+  font-size: 0.6875rem;
+  line-height: 1.25;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  opacity: 0.55;
+}
+
+.lalt-slash__shortcut {
+  flex-shrink: 0;
+  margin-left: 0.5rem;
+  padding: 0.125rem 0.375rem;
+  border: 1px solid var(--lalt-editor-border);
+  border-radius: 0.25rem;
+  font-family: ui-monospace, monospace;
+  font-size: 0.625rem;
+  opacity: 0.6;
+}
+
+/* The page a writing surface sits in.
+
+   Sized in dvh rather than vh: on mobile Safari a vh unit keeps counting the
+   browser chrome that scrolls away, so the column runs past the bottom of the
+   screen and the last paragraph is unreachable. */
+.lalt-screen {
+  display: flex;
+  flex-direction: column;
+  height: var(--lalt-screen-height, 100dvh);
+  min-height: 0;
+  color: var(--lalt-editor-text);
+}
+
+/* A host mounting the screen inside its own shell — a phone frame, a panel,
+   a route that already owns the page height — sets the height to 100% and
+   lets its container do the sizing. */
+.lalt-screen--fill {
+  --lalt-screen-height: 100%;
+}
+
+.lalt-screen__bar {
+  position: sticky;
+  top: 0;
+  z-index: 20;
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.5rem 0.75rem;
+  border-bottom: 1px solid var(--lalt-editor-border);
+  background: var(--lalt-editor-surface);
+}
+
+.lalt-screen__status {
+  min-width: 0;
+  font-size: 0.75rem;
+  font-variant-numeric: tabular-nums;
+  opacity: 0.7;
+}
+
+.lalt-screen__actions {
+  display: flex;
+  align-items: center;
+  gap: 0.375rem;
+  margin-left: auto;
+}
+
+.lalt-screen__subnav {
+  position: sticky;
+  top: 0;
+  z-index: 15;
+  border-bottom: 1px solid var(--lalt-editor-border);
+  background: var(--lalt-editor-surface);
+}
+
+/* The scroller is here, not on the body: the bar above it has to stay put
+   while the prose moves, and a document taller than the screen must not drag
+   the whole page under a raised keyboard. */
+.lalt-screen__scroll {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  -webkit-overflow-scrolling: touch;
+}
+
+.lalt-screen__column {
+  width: 100%;
+  max-width: 48rem;
+  margin: 0 auto;
+  padding: 1.25rem 1rem;
+  /* Clears the on-screen keyboard, plus room to scroll the last line up out
+     from under it. Zero wherever nothing covers the viewport. */
+  padding-bottom: calc(var(--lalt-keyboard, 0px) + 40vh);
+}
+
+/* No border, no box: the page is the document, not a form with a content
+   field in it. */
+.lalt-screen__title {
+  width: 100%;
+  border: 0;
+  background: transparent;
+  color: inherit;
+  font-family: inherit;
+  font-size: 1.5rem;
+  font-weight: 600;
+  line-height: 1.25;
+  outline: none;
+}
+
+.lalt-screen__title::placeholder {
+  opacity: 0.35;
+}
+
+.lalt-screen__aside {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: 0.5rem;
+  margin-top: 0.5rem;
+}
+
+.lalt-screen__footer {
+  margin-top: 1.5rem;
+}
+
+.lalt-screen__save {
+  display: flex;
+  flex-shrink: 0;
+  align-items: center;
+  width: 0.5rem;
+}
+
+.lalt-screen__dot {
+  width: 0.5rem;
+  height: 0.5rem;
+  border-radius: 9999px;
+  transition: background-color 150ms;
+}
+
+.lalt-screen__dot--saving {
+  background: #f59e0b;
+}
+
+.lalt-screen__dot--saved {
+  background: #10b981;
+}
+
+.lalt-screen__dot--dirty {
+  background: currentColor;
+  opacity: 0.3;
+}
+
+.lalt-screen__sr {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  border: 0;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+
+/* Room to breathe once there is a screen to spend it on. The phone layout
+   above is the one that has to work; this is the widening. */
+@media (min-width: 640px) {
+  .lalt-screen__bar {
+    padding: 0.5rem 1.5rem;
+  }
+
+  .lalt-screen__column {
+    padding: 2rem 2rem;
+    padding-bottom: calc(var(--lalt-keyboard, 0px) + 30vh);
+  }
+
+  .lalt-screen__title {
+    font-size: 1.875rem;
+  }
+}

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { R as RichDoc } from './diff-uFiP8hD5.js';
 export { B as BlockChange, a as BlockShape, C as ChangeKind, b as RichNode, c as blocksFromDoc, d as diffBlocks, e as docFromBlocks, s as shapesFromDoc } from './diff-uFiP8hD5.js';
 import * as react from 'react';
 import { Editor } from '@tiptap/react';
-import { Extension } from '@tiptap/core';
+import { Range, Extension } from '@tiptap/core';
 import { PluginKey } from '@tiptap/pm/state';
 import { DecorationSet } from '@tiptap/pm/view';
 
@@ -76,6 +76,45 @@ interface SelectionInfo {
  */
 declare function useSelectionToolbar(editor: Editor | null): SelectionInfo | null;
 
+interface VisualViewportLike {
+    width: number;
+    height: number;
+    offsetTop: number;
+}
+interface ViewportMetrics {
+    width: number;
+    height: number;
+    offsetTop: number;
+    /** How much of the layout viewport's bottom is covered, the on-screen
+     *  keyboard included. Zero on a desktop browser and wherever the API is
+     *  missing. */
+    bottomInset: number;
+}
+interface ReadViewportInput {
+    innerWidth: number;
+    innerHeight: number;
+    visual?: VisualViewportLike | null;
+}
+/**
+ * readViewport reports the area a fixed element can actually occupy.
+ *
+ * The distinction the on-screen keyboard turns on: `innerHeight` measures the
+ * layout viewport, which the keyboard covers without shrinking, so an element
+ * pinned to its bottom edge ends up underneath the keys. Only `visualViewport`
+ * narrows, and the difference is the inset a docked toolbar has to clear.
+ */
+declare function readViewport({ innerWidth, innerHeight, visual, }: ReadViewportInput): ViewportMetrics;
+
+/**
+ * useViewport tracks the area a fixed element can occupy, keyboard included.
+ *
+ * The visual viewport's own events are the only ones a raised keyboard fires:
+ * `window.resize` does not run on iOS when the keyboard opens, so a component
+ * listening to it alone keeps the measurements it took before the keys
+ * appeared.
+ */
+declare function useViewport(): ViewportMetrics;
+
 interface FormatLabels {
     paragraph: string;
     heading1: string;
@@ -93,6 +132,133 @@ declare const defaultFormatLabels: FormatLabels;
  */
 declare function blockFormats(editor: Editor | null, labels?: FormatLabels): BlockFormat[];
 
+type SaveState = "idle" | "saving" | "saved" | "dirty";
+interface EditorScreenProps {
+    /** The writing surface. Mounted by the host, which owns the TipTap instance
+     *  and whichever extensions it needs. */
+    children: React.ReactNode;
+    title?: string;
+    onTitleChange?: (title: string) => void;
+    titlePlaceholder?: string;
+    titleLabel?: string;
+    saveState?: SaveState;
+    saveLabels?: SaveLabels;
+    /** Drawn at the far left of the bar; a back control belongs here. */
+    lead?: React.ReactNode;
+    /** Drawn at the far right. Keep it to what a thumb can reach on a phone —
+     *  one primary control and an overflow, not a row of five. */
+    actions?: React.ReactNode;
+    /** Sits between the save dot and the actions: a character count, a badge. */
+    status?: React.ReactNode;
+    /** Between the title and the writing surface — a dictation control, a hint. */
+    aside?: React.ReactNode;
+    /** Below the writing surface, inside the scrolling column. */
+    footer?: React.ReactNode;
+    /** Above the writing surface and below the bar, pinned while the page
+     *  scrolls: tabs over variants of one document belong here. */
+    subnav?: React.ReactNode;
+    /** Fills its container instead of the viewport, for a host whose shell
+     *  already owns the page height. */
+    fill?: boolean;
+    className?: string;
+}
+interface SaveLabels {
+    saving: string;
+    saved: string;
+    dirty: string;
+}
+declare const defaultSaveLabels: SaveLabels;
+/**
+ * EditorScreen is the page a writing surface sits in: a command bar, a title,
+ * one column of prose, and slots for whatever the host puts around it.
+ *
+ * It renders and measures; it never fetches, saves or routes. `saveState` is
+ * displayed, not computed — the host owns the debounce and the request, so the
+ * same screen serves an autosaving draft and a form with an explicit button.
+ *
+ * Commands sit at the top rather than in a bar at the bottom. Below the fold
+ * they are gone the moment the document runs past one screen, and pinned to
+ * the bottom they eat a sixth of what the on-screen keyboard leaves.
+ */
+declare function EditorScreen({ children, title, onTitleChange, titlePlaceholder, titleLabel, saveState, saveLabels, lead, actions, status, aside, footer, subnav, fill, className, }: EditorScreenProps): react.JSX.Element;
+
+/**
+ * SlashItem is one entry of the `/` menu.
+ *
+ * icon is a node rather than a component type: the package carries no icon
+ * library, so the host renders whichever one it already ships.
+ */
+interface SlashItem {
+    id: string;
+    title: string;
+    description?: string;
+    shortcut?: string;
+    icon?: React.ReactNode;
+    command: (args: {
+        editor: Editor;
+        range: Range;
+    }) => void;
+}
+interface SlashLabels {
+    heading1: string;
+    heading2: string;
+    bulletList: string;
+    orderedList: string;
+    blockquote: string;
+    codeBlock: string;
+    horizontalRule: string;
+}
+declare const defaultSlashLabels: SlashLabels;
+interface SlashDescriptions {
+    heading1?: string;
+    heading2?: string;
+    bulletList?: string;
+    orderedList?: string;
+    blockquote?: string;
+    codeBlock?: string;
+    horizontalRule?: string;
+}
+interface DefaultSlashItemsOptions {
+    labels?: SlashLabels;
+    descriptions?: SlashDescriptions;
+    icons?: Partial<Record<DefaultSlashId, React.ReactNode>>;
+}
+type DefaultSlashId = "heading1" | "heading2" | "bulletList" | "orderedList" | "blockquote" | "codeBlock" | "horizontalRule";
+/**
+ * defaultSlashItems is the block set every writing surface shares.
+ *
+ * Returned as data rather than rendered behind flags: a host adds, removes or
+ * reorders entries by composing the array, so a surface that needs one more
+ * command does not push another boolean into this signature.
+ */
+declare function defaultSlashItems({ labels, descriptions, icons, }?: DefaultSlashItemsOptions): SlashItem[];
+/** filterSlashItems matches the query against titles the way the menu does. */
+declare function filterSlashItems(items: SlashItem[], query: string): SlashItem[];
+
+interface SlashMenuHandle {
+    onKeyDown: (props: {
+        event: KeyboardEvent;
+    }) => boolean;
+}
+interface SlashMenuProps {
+    items: SlashItem[];
+    command: (item: SlashItem) => void;
+    emptyLabel?: string;
+}
+declare const SlashMenu: react.ForwardRefExoticComponent<SlashMenuProps & react.RefAttributes<SlashMenuHandle>>;
+
+interface SlashCommandsOptions {
+    /** Read on every keystroke, so a host can swap the set without remounting
+     *  TipTap — rebuilding the extensions array wipes the text being typed. */
+    items: () => SlashItem[];
+    char: string;
+    emptyLabel?: string;
+    /** Distinguishes concurrently mounted editors: two surfaces sharing one key
+     *  would answer each other's suggestions. */
+    pluginKey: PluginKey;
+}
+declare const SlashCommands: Extension<SlashCommandsOptions, any>;
+
 interface InlineSuggestion {
     id: string;
     /** Document positions of the passage this replaces. */
@@ -157,4 +323,4 @@ declare function splitRevision(before: string, after: string): RevisionPart[];
  */
 declare function docToMarkdown(doc: RichDoc): string;
 
-export { type BlockFormat, type FormatLabels, type InlineSuggestion, InlineSuggestions, type PlaceToolbarInput, type RevisionPart, RichDoc, type SelectionInfo, type SelectionRect, SelectionToolbar, type SelectionToolbarProps, type SuggestionActions, type TextRange, type ToolbarAction, type ToolbarPlacement, blockFormats, defaultFormatLabels, docToMarkdown, expandToWords, inlineSuggestionsKey, placeToolbar, splitRevision, useSelectionToolbar };
+export { type BlockFormat, type DefaultSlashId, type DefaultSlashItemsOptions, EditorScreen, type EditorScreenProps, type FormatLabels, type InlineSuggestion, InlineSuggestions, type PlaceToolbarInput, type ReadViewportInput, type RevisionPart, RichDoc, type SaveLabels, type SaveState, type SelectionInfo, type SelectionRect, SelectionToolbar, type SelectionToolbarProps, SlashCommands, type SlashCommandsOptions, type SlashDescriptions, type SlashItem, type SlashLabels, SlashMenu, type SlashMenuHandle, type SlashMenuProps, type SuggestionActions, type TextRange, type ToolbarAction, type ToolbarPlacement, type ViewportMetrics, type VisualViewportLike, blockFormats, defaultFormatLabels, defaultSaveLabels, defaultSlashItems, defaultSlashLabels, docToMarkdown, expandToWords, filterSlashItems, inlineSuggestionsKey, placeToolbar, readViewport, splitRevision, useSelectionToolbar, useViewport };