@estiva-app/ui 0.53.1 → 0.55.0

package/dist/looks.d.ts

@@ -34,7 +34,7 @@ export declare const CHIP_TEXT_CLASSES = "text-chip signal:font-mono signal:text
 /** Words typed straight into an input with no box of its own: SearchInput and ChipInput. */
 export declare const BARE_INPUT_CLASSES = "bg-transparent text-text-primary placeholder:text-text-muted outline-none";
 /** A sidebar row's shape and its words at rest, brightening under the pointer: NavItem, and SectionHeader's `row` (a folder among rows). */
-export declare const SIDEBAR_ROW_CLASSES = "rounded-md transition-colors";
+export declare const SIDEBAR_ROW_CLASSES = "rounded-lg transition-colors";
 export declare const SIDEBAR_ROW_TEXT_CLASSES = "text-text-secondary hover:text-text-primary";
 /**
  * A panel that slides open and shut on Base UI's Collapsible: Base UI measures

package/dist/looks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"looks.d.ts","sourceRoot":"","sources":["../src/looks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;GAEG;AACH,eAAO,MAAM,iBAAiB,2MAA2M,CAAA;AAEzO,wFAAwF;AACxF,eAAO,MAAM,kBAAkB,kDAAkD,CAAA;AAEjF,mEAAmE;AACnE,eAAO,MAAM,sBAAsB,iKAAiK,CAAA;AAEpM,wEAAwE;AACxE,eAAO,MAAM,wBAAwB,4DAA4D,CAAA;AAEjG,kJAAkJ;AAClJ,eAAO,MAAM,kBAAkB;;;CAGrB,CAAA;AAEV,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,uJAAuJ,CAAA;AAEvL,mEAAmE;AACnE,eAAO,MAAM,wBAAwB,qEAAqE,CAAA;AAE1G,yDAAyD;AACzD,eAAO,MAAM,iBAAiB,0FAA0F,CAAA;AAExH,4FAA4F;AAC5F,eAAO,MAAM,kBAAkB,8EAA8E,CAAA;AAE7G,4IAA4I;AAC5I,eAAO,MAAM,mBAAmB,iCAAiC,CAAA;AACjE,eAAO,MAAM,wBAAwB,gDAAgD,CAAA;AAErF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,kLAAkL,CAAA"}
+{"version":3,"file":"looks.d.ts","sourceRoot":"","sources":["../src/looks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;GAEG;AACH,eAAO,MAAM,iBAAiB,2MAA2M,CAAA;AAEzO,wFAAwF;AACxF,eAAO,MAAM,kBAAkB,kDAAkD,CAAA;AAEjF,mEAAmE;AACnE,eAAO,MAAM,sBAAsB,iKAAiK,CAAA;AAEpM,wEAAwE;AACxE,eAAO,MAAM,wBAAwB,4DAA4D,CAAA;AAEjG,kJAAkJ;AAClJ,eAAO,MAAM,kBAAkB;;;CAGrB,CAAA;AAEV,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,uJAAuJ,CAAA;AAEvL,mEAAmE;AACnE,eAAO,MAAM,wBAAwB,qEAAqE,CAAA;AAE1G,yDAAyD;AACzD,eAAO,MAAM,iBAAiB,0FAA0F,CAAA;AAExH,4FAA4F;AAC5F,eAAO,MAAM,kBAAkB,8EAA8E,CAAA;AAE7G,4IAA4I;AAE5I,eAAO,MAAM,mBAAmB,iCAAiC,CAAA;AACjE,eAAO,MAAM,wBAAwB,gDAAgD,CAAA;AAErF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,kLAAkL,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.53.1",
+  "version": "0.55.0",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",

package/registry.json

@@ -4,9 +4,9 @@
     "kind": "package",
     "repo": "estiva-ui",
     "package": "@estiva-app/ui",
-    "packageVersion": "0.53.1",
-    "exports": 120,
-    "typeExports": 128,
+    "packageVersion": "0.55.0",
+    "exports": 130,
+    "typeExports": 134,
     "files": null
   },
   "storybook": {
@@ -458,6 +458,88 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "blockAtY",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/BlockHandle.tsx",
+      "purpose": "The last of `blocks` whose top is at or above `y` — the gap between two blocks belongs to the one before.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-blockhandle--docs",
+      "storyId": "primitives-blockhandle--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "blockDropCursor",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/EditorBlockHandle.tsx",
+      "purpose": "The drop line a dragged block shows, in the package's accent instead of the editor's default (the text's colour).",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-editorblockhandle--docs",
+      "storyId": "primitives-editorblockhandle--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "BlockHandle",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/BlockHandle.tsx",
+      "purpose": "The handle left of the block under the pointer, as a block-document page has it, and the block's menu behind it.",
+      "purposeFrom": "page",
+      "props": [
+        {
+          "name": "actions",
+          "takes": "a handler",
+          "required": false,
+          "note": "The caller's own rows — a link to the block, a comment on it."
+        },
+        {
+          "name": "editing",
+          "takes": "BlockHandleEditing",
+          "required": false,
+          "note": "Given by `EditorBlockHandle` (from `@estiva-app/ui/editor`)."
+        },
+        {
+          "name": "children",
+          "takes": "anything",
+          "required": true,
+          "note": "What the blocks are drawn in. Reading: a surface whose top-level elements carry `data-block-id`, as `RichText` draws."
+        },
+        {
+          "name": "className",
+          "takes": "text",
+          "required": false,
+          "note": null
+        }
+      ],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-blockhandle--docs",
+      "storyId": "primitives-blockhandle--default",
+      "docPage": "src/BlockHandle.mdx",
+      "app": null,
+      "looks": []
+    },
     {
       "name": "BlockId",
       "repo": "estiva-ui",
@@ -1691,6 +1773,25 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "deleteBlock",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/EditorBlockHandle.tsx",
+      "purpose": "Removes the block, the caret where it was.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-editorblockhandle--docs",
+      "storyId": "primitives-editorblockhandle--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "DialogShell",
       "repo": "estiva-ui",
@@ -1864,6 +1965,25 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "duplicateBlock",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/EditorBlockHandle.tsx",
+      "purpose": "A copy of the block straight after it, the caret in the copy.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-editorblockhandle--docs",
+      "storyId": "primitives-editorblockhandle--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "EditableText",
       "repo": "estiva-ui",
@@ -1951,6 +2071,56 @@
         "rounded-md border border-transparent text-left transition-colors hover:border-border-default"
       ]
     },
+    {
+      "name": "EditorBlockHandle",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/EditorBlockHandle.tsx",
+      "purpose": "`BlockHandle` in a Tiptap editor: drag the handle to move the block, press it for Turn into, Duplicate and Delete, then the app's rows.",
+      "purposeFrom": "page",
+      "props": [
+        {
+          "name": "editor",
+          "takes": "Editor | null",
+          "required": true,
+          "note": "The editor. Not editable, or not there yet, and the handle reads: the caller's rows only."
+        },
+        {
+          "name": "turnInto",
+          "takes": "readonly BlockTurnInto[]",
+          "required": false,
+          "note": "Turn into's rows. Offered for a block of text — a paragraph, a heading, code."
+        },
+        {
+          "name": "actions",
+          "takes": "a handler",
+          "required": false,
+          "note": "The caller's own rows, after the editing ones."
+        },
+        {
+          "name": "children",
+          "takes": "anything",
+          "required": true,
+          "note": "The `EditorContent`."
+        },
+        {
+          "name": "className",
+          "takes": "text",
+          "required": false,
+          "note": null
+        }
+      ],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-editorblockhandle--docs",
+      "storyId": "primitives-editorblockhandle--default",
+      "docPage": "src/EditorBlockHandle.mdx",
+      "app": null,
+      "looks": []
+    },
     {
       "name": "EmptyState",
       "repo": "estiva-ui",
@@ -3594,6 +3764,25 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "moveBlock",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/EditorBlockHandle.tsx",
+      "purpose": "Moves the block at `from` to `to` (a position between top-level blocks), the caret in it: what a drop in the gutter does, where the editor has no drop of its own.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-editorblockhandle--docs",
+      "storyId": "primitives-editorblockhandle--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "NavItem",
       "repo": "estiva-ui",
@@ -3657,6 +3846,18 @@
           "required": false,
           "note": "Shown only while the row is pointed at or focused, left of the count: a neutral `Chip`, typically."
         },
+        {
+          "name": "unread",
+          "takes": "true/false",
+          "required": false,
+          "note": "Something new here: brighter words, the label in medium, and the `UnreadDot` at the right."
+        },
+        {
+          "name": "urgent",
+          "takes": "true/false",
+          "required": false,
+          "note": "With `unread`: the warning badge in the dot's place."
+        },
         {
           "name": "children",
           "takes": "anything",
@@ -3702,8 +3903,9 @@
       "docPage": "src/NavItem.mdx",
       "app": null,
       "looks": [
-        "text-body-2 rounded-md transition-colors bg-bg-active text-text-primary",
-        "text-body-2 rounded-md transition-colors text-text-secondary hover:text-text-primary hover:bg-bg-hover",
+        "text-body-2 rounded-lg transition-colors bg-bg-nav-active text-text-primary",
+        "text-body-2 rounded-lg transition-colors text-text-primary hover:bg-bg-hover",
+        "text-body-2 rounded-lg transition-colors text-text-secondary hover:text-text-primary hover:bg-bg-hover",
         "text-center font-mono text-caption tabular-nums text-text-muted",
         "text-center font-mono text-caption tabular-nums text-text-muted transition-opacity",
         "overflow-hidden transition-[height] duration-150 ease-out motion-reduce:transition-none"
@@ -3724,11 +3926,23 @@
           "required": false,
           "note": "The quiet label over the groups. Absent, none is drawn."
         },
+        {
+          "name": "titleActions",
+          "takes": "SectionAction[]",
+          "required": false,
+          "note": "Beside the label, always shown: \"New\", typically."
+        },
         {
           "name": "groups",
           "takes": "NavTreeGroup[] | null",
-          "required": true,
-          "note": "`null` while the first read is on its way: a skeleton in the rows' place."
+          "required": false,
+          "note": "`null` while the first read is on its way: a skeleton in the groups' place."
+        },
+        {
+          "name": "children",
+          "takes": "anything",
+          "required": false,
+          "note": "The groups, drawn by the app: `NavTreeSection`s with `NavItem` rows — for an app whose groups and rows each read their own data."
         },
         {
           "name": "selected",
@@ -3745,8 +3959,8 @@
         {
           "name": "emptyMessage",
           "takes": "text",
-          "required": true,
-          "note": "What to say when there are no groups. The words are the caller's."
+          "required": false,
+          "note": "What to say when `groups` is empty. The words are the caller's; absent, nothing is said."
         },
         {
           "name": "storageKey",
@@ -3765,6 +3979,98 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "NavTreeSection",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/NavTree.tsx",
+      "purpose": "One group of a `NavTree`, for an app that draws its own: the standard heading folding its rows, lightly indented under its title, with the group's line, skeleton, actions and `onIntent`.",
+      "purposeFrom": "comment",
+      "props": [
+        {
+          "name": "title",
+          "takes": "text",
+          "required": true,
+          "note": null
+        },
+        {
+          "name": "id",
+          "takes": "text",
+          "required": false,
+          "note": "Marks the group's box as `data-nav-group`, for tests and photo runs to find it."
+        },
+        {
+          "name": "message",
+          "takes": "text",
+          "required": false,
+          "note": "Said in the rows' place, level with them."
+        },
+        {
+          "name": "trailing",
+          "takes": "anything",
+          "required": false,
+          "note": "Beside the title, always shown: an `UnreadDot`, typically."
+        },
+        {
+          "name": "actions",
+          "takes": "SectionAction[]",
+          "required": false,
+          "note": "Beside the title, shown on hover or focus: \"Open\", typically."
+        },
+        {
+          "name": "defaultOpen",
+          "takes": "true/false",
+          "required": false,
+          "note": "Open unless told otherwise."
+        },
+        {
+          "name": "open",
+          "takes": "true/false",
+          "required": false,
+          "note": "The caller owns whether the group is open."
+        },
+        {
+          "name": "onOpenChange",
+          "takes": "a handler",
+          "required": false,
+          "note": null
+        },
+        {
+          "name": "onIntent",
+          "takes": "a handler",
+          "required": false,
+          "note": "The pointer rests on the group, or the keyboard reaches it: read its rows now."
+        },
+        {
+          "name": "loading",
+          "takes": "true/false",
+          "required": false,
+          "note": "Its rows are being read: a skeleton in their place."
+        },
+        {
+          "name": "storageKey",
+          "takes": "text",
+          "required": false,
+          "note": "Remember it open or closed in this browser, under this key."
+        },
+        {
+          "name": "children",
+          "takes": "anything",
+          "required": false,
+          "note": "The rows: `NavItem`s."
+        }
+      ],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "frame-navtree--docs",
+      "storyId": "frame-navtree--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "normalizeHref",
       "repo": "estiva-ui",
@@ -4979,8 +5285,8 @@
       "app": null,
       "looks": [
         "transition-transform duration-150 text-text-secondary rotate-90",
-        "rounded-md transition-colors text-text-secondary hover:text-text-primary",
-        "rounded-md transition-colors text-text-secondary hover:text-text-primary hover:bg-bg-hover",
+        "rounded-lg transition-colors text-text-secondary hover:text-text-primary",
+        "rounded-lg transition-colors text-text-secondary hover:text-text-primary hover:bg-bg-hover",
         "-mr-1 opacity-0 transition-opacity focus-within:opacity-100 group-hover:opacity-100",
         "opacity-0 transition-opacity focus-within:opacity-100 group-hover:opacity-100"
       ]
@@ -5415,6 +5721,25 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "startBlockDrag",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/EditorBlockHandle.tsx",
+      "purpose": "Starts the browser's own drag of the block, as ProseMirror starts one of a selected node: the block selected, its slice on `view.dragging` with `move`, and its HTML on the transfer.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-editorblockhandle--docs",
+      "storyId": "primitives-editorblockhandle--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "SuggestionMenu",
       "repo": "estiva-ui",
@@ -6472,6 +6797,32 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "UnreadDot",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/UnreadDot.tsx",
+      "purpose": "The accent dot that says \"something new here\": a 6px disc centred in a 24px slot, so it sits exactly where a control would and the row does not shift when one replaces the other.",
+      "purposeFrom": "page",
+      "props": [
+        {
+          "name": "className",
+          "takes": "text",
+          "required": false,
+          "note": null
+        }
+      ],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-unreaddot--docs",
+      "storyId": "primitives-unreaddot--default",
+      "docPage": "src/UnreadDot.mdx",
+      "app": null,
+      "looks": []
+    },
     {
       "name": "UrgentPersonMention",
       "repo": "estiva-ui",

package/src/BlockHandle.mdx

@@ -0,0 +1,58 @@
+import { Meta, Canvas } from '@storybook/addon-docs/blocks'
+import * as BlockHandleStories from './BlockHandle.stories'
+
+<Meta of={BlockHandleStories} />
+
+# BlockHandle
+
+The handle left of the block under the pointer, as a block-document page has
+it, and the block's menu behind it. Over a document being read, the menu is
+the app's rows only — a link to the block, a comment on it.
+
+<Canvas of={BlockHandleStories.Default} />
+
+## When
+
+- **A document made of blocks, read by someone who cannot edit it**, when the
+  app has something to offer on one block: a link to it, a comment on it.
+
+## When not
+
+- The same document being edited → **EditorBlockHandle**, from
+  `@estiva-app/ui/editor`: the same handle, which also drags and has Turn
+  into, Duplicate and Delete.
+- Reading a document with nothing to offer on one block → **RichText** alone.
+
+## How
+
+```tsx
+import { BlockHandle, MenuItem, RichText, type HandleBlock, type RichTextBlock } from '@estiva-app/ui'
+
+const blocks: RichTextBlock[] = [{ type: 'paragraph', id: 'b1', inline: [{ text: 'Label', marks: [] }] }]
+const rows = (block: HandleBlock) => <MenuItem label="Copy link" onClick={() => navigator.clipboard.writeText(`#${block.id}`)} />
+
+<BlockHandle actions={rows}>
+  <RichText blocks={blocks} />
+</BlockHandle>
+```
+
+- **Leave room on the left.** The handle sits 28px left of the content, in
+  the page's margin, so wrapping the content moves nothing. A surface flush
+  with its container's left edge clips it.
+- `children` is a surface whose top-level elements carry `data-block-id`, as
+  `RichText` draws them. `HandleBlock.id` is that §13.3 id: what a link or a
+  comment addresses.
+- With no `actions`, or `actions` that return nothing for a block, no handle
+  is drawn.
+- **In the main entry on purpose**: a reader must not download an editor.
+  `editing` is how `EditorBlockHandle` makes this part edit, not a prop to
+  fill by hand.
+
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Finds the block under the pointer, by height: the gap between two blocks belongs to the one above | a pointer handler on each block | |
+| Centres the handle on the block's first line, a heading's or a paragraph's | a position for the handle | |

package/src/BlockHandle.stories.tsx

@@ -0,0 +1,44 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconLink, IconMessage } from '@tabler/icons-react'
+import { BlockHandle, type HandleBlock } from './BlockHandle'
+import { MenuItem } from './Menu'
+import { RichText, type RichTextBlock } from './RichText'
+
+/**
+ * The handle left of the block under the pointer, over a document being read:
+ * press it for the app's rows. In an editor, `EditorBlockHandle` adds the drag
+ * and the editing rows.
+ */
+const meta = {
+  title: 'Primitives/BlockHandle',
+  // The handle sits 28px left of the content, in the page's margin.
+  parameters: { layout: 'padded' },
+} satisfies Meta
+
+export default meta
+type Story = StoryObj
+
+/** The rows an app adds: here they only say which block they were pressed on. */
+function rows(block: HandleBlock) {
+  return (
+    <>
+      <MenuItem label="Copy link" leading={<IconLink size={16} stroke={1.5} className="text-text-secondary" />} onClick={() => console.info('copy link', block.id)} />
+      <MenuItem label="Comment" leading={<IconMessage size={16} stroke={1.5} className="text-text-secondary" />} onClick={() => console.info('comment', block.id)} />
+    </>
+  )
+}
+
+const READING: RichTextBlock[] = [
+  { type: 'heading', level: 1, id: 'b1', inline: [{ text: 'A heading', marks: [] }] },
+  { type: 'paragraph', id: 'b2', inline: [{ text: 'Someone who cannot edit this still gets the handle, with the app’s rows only.', marks: [] }] },
+  { type: 'paragraph', id: 'b3', inline: [{ text: 'The second paragraph.', marks: [] }] },
+]
+
+/** Reading: no drag and no editing rows — only what the app adds. */
+export const Default: Story = {
+  render: () => (
+    <BlockHandle actions={rows} className="ml-8 max-w-[560px]">
+      <RichText blocks={READING} />
+    </BlockHandle>
+  ),
+}