@inkbar/theme 0.10.0 → 0.12.0

package/README.md

@@ -20,7 +20,7 @@
 
 ---
 
-`@inkbar/theme` styles the viewer, toolbar controls and note threads from `@inkbar/vue`, `@inkbar/react`, `@inkbar/svelte` and `createViewer` in `@inkbar/core`. Import it and ship, or override any part of it with your own CSS. If your app already defines shadcn tokens, the theme picks up your colours and radius.
+`@inkbar/theme` styles the viewer and what it draws over pages (annotations, form fields, search matches), the toolbar controls and menus, sidebars and thumbnails, the find bar and search results, the signature dialog, note threads, and plugin cards and command buttons, from `@inkbar/vue`, `@inkbar/react`, `@inkbar/svelte` and `createViewer` in `@inkbar/core`. Import it and ship, or override any part of it with your own CSS. If your app already defines shadcn tokens, the theme picks up your colours and radius.
 
 ## Install
 
@@ -34,7 +34,7 @@ Import the stylesheet once in your app:
 import '@inkbar/theme/theme.css'
 ```
 
-Every rule sits in `@layer inkbar` and inside `:where()`, so each selector has zero specificity. Your unlayered CSS overrides it without `!important`.
+Every rule sits in `@layer inkbar` and inside `:where()`, so each selector has zero specificity. Your unlayered CSS overrides it without `!important`. The one exception is the move cursor while an annotation is dragged (`[data-ink-dragging]`), which uses `!important` to show over every element's own cursor.
 
 ## Layer order
 
@@ -66,14 +66,15 @@ Set these variables on `[data-ink-root]` to change the default colour for new an
 | `--ink-note`, `--ink-free-text`                                           | Notes and text boxes        |
 | `--ink-shape`, `--ink-ink`                                                | Shapes and freehand drawing |
 | `--ink-redact`, `--ink-redact-fill`                                       | Redaction outline and fill  |
+| `--ink-mask`                                                              | Masks                       |
 
-Inkbar reads a colour when you create the annotation and stores it on the annotation, because the colour goes into the PDF. Changing a variable later affects new annotations only.
+Inkbar reads a colour when you create the annotation and stores it on the annotation, because the colour goes into the PDF. Changing a variable later affects new annotations only. Write these as hex (`#f2c230`) or `rgb()`: Inkbar ignores other formats and uses its own default.
 
 ## Layout
 
 The root and viewport fill their parent as a column, and the scroll area takes the remaining height. Give the parent a height and the document scrolls inside it.
 
-The theme gives a toolbar a background and padding and styles the controls in it. You decide where the toolbar sits, how to group its controls and what separates it from the document. Set `--ink-control-size` on a toolbar to change the height of its buttons, fields and zoom select (default `2.25rem`), and `--ink-icon-size` to change the size of their icons (default `1.125rem`).
+The theme gives a toolbar a background and padding and styles the controls in it. You decide where the toolbar sits, how to group its controls and what separates it from the document. Set `--ink-control-size` on a toolbar to change the height of its buttons, fields and zoom select (default `2.25rem`), and `--ink-icon-size` to change the size of their icons (default `1.125rem`). `--ink-control-size` also sizes the sidebar rail's buttons and any `ink-select`.
 
 ```css
 .my-page-bar {
@@ -83,9 +84,23 @@ The theme gives a toolbar a background and padding and styles the controls in it
 }
 ```
 
+Sidebars and thumbnails have their own sizes:
+
+| Variable                   | Default | Sets                                                |
+| -------------------------- | ------- | --------------------------------------------------- |
+| `--ink-sidebar-width`      | `320px` | An open sidebar's width; the sidebar sets it inline |
+| `--ink-sidebar-rail-width` | `48px`  | The width of a sidebar's icon rail                  |
+| `--ink-thumbnail-width`    | `120px` | The width of a page thumbnail                       |
+
+The sidebar always sets `--ink-sidebar-width` inline, even when no width is saved, so a CSS override of it no longer applies. Pass the sidebar's `defaultWidth` instead. Style the handle with `.ink-sidebar-handle`. It draws a 2px `--ink-accent` line on hover, focus and while dragging.
+
+## Search, form and link colours
+
+`--ink-search-hit` and `--ink-search-current` colour search matches and the current match. `--ink-mark-selected-outline` outlines a plugin mark whose record is selected (default `2px solid #2740f5`). `--ink-form-field-bg`, `--ink-form-field-focus` and `--ink-form-field-invalid` colour form fields, the focused field and a field that fails its check. `--ink-link-hover` tints a link under the pointer (default `transparent`, so links show no box).
+
 ## Your own controls
 
-Two classes give your own controls the look of the built-in ones. Add `ink-select` to a `<select>` to give it the zoom select's box and chevron. To put an icon in a field, wrap the input in `ink-input-group` and add an `ink-input-accessory` before it for an icon at the start, or after it for one at the end. The icon lets clicks through to the field, and the input makes room for it. The find bar and the search results field use this for their search icon.
+Three classes give your own controls the look of the built-in ones. Add `ink-select` to a `<select>` to give it the zoom select's box and chevron. To put an icon in a field, wrap the input in `ink-input-group` and add an `ink-input-accessory` before it for an icon at the start, or after it for one at the end. The icon lets clicks through to the field, and the input makes room for it. The find bar and the search results field use this for their search icon.
 
 ```html
 <select class="ink-select">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inkbar/theme",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Default stylesheet for Inkbar. Zero specificity, so your CSS wins.",
   "license": "MIT",
   "homepage": "https://inkbar.dev",

package/theme.css

@@ -37,12 +37,19 @@
     /* Pages stay white in dark mode and the search layer multiplies, so these serve both. */
     --ink-search-hit: #f1ffa0;
     --ink-search-current: #e4ff4a;
+    /* A tint over a link under the pointer; off by default, as desktop readers show no box. */
+    --ink-link-hover: transparent;
     /* The selected record's mark; pages stay white in dark mode, so this serves both. */
     --ink-mark-selected-outline: 2px solid #2740f5;
     /* Sidebars (createSidebar and the bindings' sidebar): the open sidebar and its rail. */
-    --ink-sidebar-width: 280px;
+    --ink-sidebar-width: 320px;
     --ink-sidebar-rail-width: 48px;
     --ink-thumbnail-width: 120px;
+    /* The outline (createOutline and the bindings' outline): indent per level, item height and
+       the current item's tint. */
+    --ink-outline-indent: 16px;
+    --ink-outline-item-height: 44px;
+    --ink-outline-current-bg: color-mix(in srgb, var(--ink-accent) 10%, transparent);
 
     --ink-bg: var(--muted, #f1f2f5);
     --ink-fg: var(--foreground, #151820);
@@ -351,6 +358,30 @@
     border-radius: 50%;
   }
 
+  /* Links: over the text layer, under the search matches, fields and annotations. They never
+     take the pointer (the viewer hit-tests links itself, so selection and tools work over
+     them), so they show only as a ring while focused from the keyboard, on every line of a
+     wrapped link, and as the hover tint the viewer turns on with data-ink-hover. */
+  :where(.ink-link-layer) {
+    z-index: 1;
+    pointer-events: none;
+  }
+
+  :where(.ink-link) {
+    pointer-events: none;
+    border-radius: 2px;
+    outline: none;
+  }
+
+  :where(.ink-link:focus-visible, .ink-link[data-ink-focused]) {
+    outline: 2px solid var(--ink-ring);
+    outline-offset: 1px;
+  }
+
+  :where(.ink-link[data-ink-hover]) {
+    background: var(--ink-link-hover);
+  }
+
   /* Search matches sit under the annotations: before the overlay in the page, same level. The
      layer multiplies with the page, so dark text shows through as if the page were marked. */
   :where(.ink-search-layer) {
@@ -837,6 +868,7 @@
    * mirrors them.
    */
   :where(.ink-sidebar) {
+    position: relative;
     box-sizing: border-box;
     display: flex;
     flex-direction: column;
@@ -918,6 +950,58 @@
     display: none;
   }
 
+  /* The resize handle: a strip straddling the inner edge, wider for fingers. touch-action keeps
+     a touch drag from scrolling the page instead. */
+  :where(.ink-sidebar-handle) {
+    position: absolute;
+    top: 0;
+    bottom: 0;
+    right: -4px;
+    width: 8px;
+    cursor: col-resize;
+    touch-action: none;
+    z-index: 1;
+  }
+
+  :where(.ink-sidebar[data-side='right'] .ink-sidebar-handle) {
+    right: auto;
+    left: -4px;
+  }
+
+  @media (pointer: coarse) {
+    :where(.ink-sidebar-handle) {
+      right: -8px;
+      width: 16px;
+    }
+
+    :where(.ink-sidebar[data-side='right'] .ink-sidebar-handle) {
+      right: auto;
+      left: -8px;
+    }
+  }
+
+  :where(.ink-sidebar-handle[hidden]) {
+    display: none;
+  }
+
+  :where(
+    .ink-sidebar-handle:hover,
+    .ink-sidebar-handle:focus-visible,
+    .ink-sidebar[data-resizing] .ink-sidebar-handle
+  ) {
+    background: linear-gradient(
+      to right,
+      transparent calc(50% - 1px),
+      var(--ink-accent) calc(50% - 1px),
+      var(--ink-accent) calc(50% + 1px),
+      transparent calc(50% + 1px)
+    );
+  }
+
+  :where(.ink-sidebar[data-resizing]) {
+    user-select: none;
+  }
+
   /* Not visible: the whole sidebar goes, its state kept. After every display rule above. */
   :where(.ink-sidebar[hidden]) {
     display: none;
@@ -2150,6 +2234,127 @@
     font-size: 0.875rem;
   }
 
+  /*
+   * The outline (createOutline and the bindings' outline): a tree that fills its parent's height
+   * and scrolls. Each item is indented by its level, which the renderer sets as
+   * --ink-outline-level (0 at the top), and is at least 44px tall to stay easy to tap.
+   */
+  :where(.ink-outline) {
+    box-sizing: border-box;
+    height: 100%;
+    min-height: 0;
+    overflow-x: hidden;
+    overflow-y: auto;
+  }
+
+  :where(.ink-outline-tree, .ink-outline-group) {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  :where(.ink-outline-tree) {
+    padding: 0.5rem;
+  }
+
+  :where(
+    .ink-outline-tree[hidden],
+    .ink-outline-group[hidden],
+    .ink-outline-empty[hidden]
+  ) {
+    display: none;
+  }
+
+  /* The item holds its children's group, so what is the item's alone sits on its row. */
+  :where(.ink-outline-item) {
+    outline: none;
+  }
+
+  :where(.ink-outline-row) {
+    box-sizing: border-box;
+    display: flex;
+    align-items: center;
+    gap: 0.25rem;
+    min-height: var(--ink-outline-item-height, 44px);
+    padding: 0 0.5rem 0
+      calc(var(--ink-outline-level, 0) * var(--ink-outline-indent, 16px));
+    border-radius: calc(var(--ink-radius) - 2px);
+    font-size: 0.875rem;
+    line-height: 1.3;
+    cursor: pointer;
+  }
+
+  :where(.ink-outline-row:hover) {
+    background: color-mix(in srgb, var(--ink-fg) 6%, transparent);
+  }
+
+  :where(.ink-outline-item:focus-visible > .ink-outline-row) {
+    outline: 2px solid var(--ink-ring);
+    outline-offset: -2px;
+  }
+
+  :where(.ink-outline-item[aria-current='location'] > .ink-outline-row) {
+    background: var(--ink-outline-current-bg);
+    color: var(--ink-fg);
+    box-shadow: inset 2px 0 0 var(--ink-accent);
+  }
+
+  :where(.ink-outline-item[data-bold] > .ink-outline-row) {
+    font-weight: 600;
+  }
+
+  :where(.ink-outline-item[data-italic] > .ink-outline-row) {
+    font-style: italic;
+  }
+
+  /* Items Inkbar cannot follow (another file, an app, an unsafe URL) stay listed, greyed out. */
+  :where(.ink-outline-item[aria-disabled='true'] > .ink-outline-row) {
+    color: var(--ink-muted-fg);
+    cursor: default;
+  }
+
+  :where(.ink-outline-item[aria-disabled='true'] > .ink-outline-row:hover) {
+    background: transparent;
+  }
+
+  /* Touch can only expand an item by its chevron, and a near miss follows the item instead, so
+     the chevron gets a full 44px column of the row. A leaf keeps the column empty, so titles
+     line up. */
+  :where(.ink-outline-toggle, .ink-outline-spacer) {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    align-self: stretch;
+    justify-content: center;
+    width: 44px;
+    min-height: 44px;
+    color: var(--ink-muted-fg);
+  }
+
+  :where(.ink-outline-toggle > svg) {
+    width: 1rem;
+    height: 1rem;
+  }
+
+  :where(
+    .ink-outline-item[aria-expanded='true'] > .ink-outline-row > .ink-outline-toggle > svg
+  ) {
+    transform: rotate(90deg);
+  }
+
+  :where(.ink-outline-title) {
+    min-width: 0;
+    padding-block: 0.375rem;
+    overflow-wrap: anywhere;
+  }
+
+  :where(.ink-outline-empty) {
+    margin: 0;
+    padding: 1rem 0.75rem;
+    color: var(--ink-muted-fg);
+    font-size: 0.875rem;
+  }
+
   /*
    * Search results frame their cards as the viewer frames its pages: the field on the surface
    * at the top, the cards on the page canvas, and the count in a footer on the surface at the
@@ -2363,5 +2568,9 @@
     :where(.ink-annotation) {
       transition: outline-color 120ms ease;
     }
+
+    :where(.ink-outline-toggle > svg) {
+      transition: transform 120ms ease-out;
+    }
   }
 }