@lovett/ui 0.0.11 → 0.2.0

package/src/lib/focus.ts

@@ -27,6 +27,48 @@ export function tabbablesWithin(root: HTMLElement): HTMLElement[] {
       el.tabIndex >= 0 &&
       !el.hasAttribute('inert') &&
       el.getAttribute('aria-hidden') !== 'true' &&
-      !el.closest('[hidden]'),
+      !el.closest('[hidden]') &&
+      // `inert` is INHERITED by the subtree in a browser, so a control inside
+      // an inert ancestor cannot take focus — a trap that hands it focus
+      // anyway simply stops moving. The detail surface collapses a pane by
+      // making it inert rather than unmounting it (its scroll and its drafts
+      // have to survive), which is the case that made this ancestor check
+      // load-bearing rather than tidy.
+      !el.closest('[inert]'),
   )
 }
+
+/**
+ * Keep Tab inside `container`.
+ *
+ * `Popover` is non-modal by design: it moves focus in and hands it back, but
+ * Tab walks straight out of it into the page behind. For a surface that is a
+ * self-contained panel of controls — the Display popover, the filter picker —
+ * that reads as the panel losing focus mid-use, so those surfaces wrap the
+ * cycle themselves. Call from a `keydown` handler on the container.
+ *
+ * Does nothing unless the key is Tab, and nothing when the container holds
+ * fewer than two tabbables (a single control has nowhere to cycle to and
+ * preventing default there would trap the user on it).
+ */
+export function handleTabTrap(
+  event: { key: string; shiftKey: boolean; preventDefault: () => void },
+  container: HTMLElement | null,
+): void {
+  if (event.key !== 'Tab' || !container) return
+  const tabbables = tabbablesWithin(container)
+  if (tabbables.length < 2) return
+  const first = tabbables[0]
+  const last = tabbables[tabbables.length - 1]
+  if (!first || !last) return
+  const active = document.activeElement
+  if (event.shiftKey && (active === first || !container.contains(active))) {
+    event.preventDefault()
+    last.focus()
+    return
+  }
+  if (!event.shiftKey && active === last) {
+    event.preventDefault()
+    first.focus()
+  }
+}

package/src/lib/layer-stack.ts

@@ -58,7 +58,23 @@ export interface LayerHandle {
 }
 
 interface LayerRecord {
-  readonly kind: LayerKind
+  /**
+   * MUTABLE, and the one field that is.
+   *
+   * A surface whose kind CHANGES while it is open must not lose its place in
+   * the stack over it. The item detail is the case that found this: its three
+   * modes are one element tree, and `panel` is non-modal while `full` and
+   * `modal` are, so switching mode flips this from 'modal' to 'popover'. When
+   * `kind` was an effect dependency, that flip popped and re-pushed the
+   * layer — landing the detail ABOVE a dropdown menu that was already open,
+   * so the next Escape closed the whole detail instead of the menu inside it.
+   * (Switching mode is done FROM that menu, so it was the common path, not an
+   * edge case.)
+   *
+   * Updating in place keeps push order meaning what it says: the order things
+   * OPENED, not the order they last changed shape.
+   */
+  kind: LayerKind
   readonly element: () => HTMLElement | null
   readonly onEscape: (event: KeyboardEvent) => void
 }
@@ -119,12 +135,17 @@ export function useLayer(options: UseLayerOptions): LayerHandle {
     onEscapeRef.current = onEscape
   })
 
+  // Read through a ref for the same reason `onEscape` is: so that changing it
+  // updates the layer rather than reordering the stack. See `LayerRecord.kind`.
+  const kindRef = useRef(kind)
+  kindRef.current = kind
+
   const recordRef = useRef<LayerRecord | null>(null)
 
   useEffect(() => {
     if (!enabled) return
     const record: LayerRecord = {
-      kind,
+      kind: kindRef.current,
       element: () => elementRef?.current ?? null,
       onEscape: (event) => onEscapeRef.current(event),
     }
@@ -134,7 +155,13 @@ export function useLayer(options: UseLayerOptions): LayerHandle {
       pop()
       if (recordRef.current === record) recordRef.current = null
     }
-  }, [enabled, kind, elementRef])
+  }, [enabled, elementRef])
+
+  // A kind change updates the record IN PLACE, keeping its position.
+  useEffect(() => {
+    const record = recordRef.current
+    if (record !== null) record.kind = kind
+  }, [kind])
 
   return useMemo<LayerHandle>(
     () => ({

package/src/lib/remark-underline.ts

@@ -0,0 +1,443 @@
+/**
+ * remark-underline — `++text++` renders as `<u>` (ADR-148 D13).
+ *
+ * Markdown has no underline. The rich composer serialises TipTap's
+ * `underline` mark as `++text++` — a dialect several Markdown flavours use
+ * for insert/underline, and one CommonMark cannot misread because `+` has no
+ * inline meaning. This is the RENDERER half: a micromark text construct that
+ * tokenizes `++` runs, a resolver that pairs openers with closers, and an
+ * mdast handler that emits an `underline` node carrying `data.hName = 'u'`,
+ * which `remark-rehype` turns into a `<u>` element for the component map in
+ * `markdown.tsx` to style.
+ *
+ * ZERO DEPENDENCIES, ON PURPOSE. `remark-gfm` already pulls every utility this
+ * would want into the lockfile (`micromark-util-classify-character`,
+ * `micromark-util-resolve-all`, `micromark-util-chunked`,
+ * `mdast-util-from-markdown`, `micromark-util-types`) — but pnpm's strict
+ * layout keeps transitives out of `packages/ui/node_modules`, so none of them
+ * is importable here without becoming a direct dependency, which D13 forbids.
+ * The three helpers are re-derived below (each is under fifteen lines in the
+ * original) and the types are local structural mirrors of
+ * `micromark-util-types` / `mdast-util-from-markdown`. The runtime contract is
+ * plain objects and functions that micromark calls by shape, so a mirror is
+ * exactly as safe as the import would be. The construct is modelled line for
+ * line on `micromark-extension-gfm-strikethrough` (`~~` → `<del>`), its
+ * closest cousin.
+ *
+ * THE RULES — agreed with the composer's serializer (ADR-148 D13):
+ *
+ *   • A `++` run may OPEN / CLOSE by exactly GFM strikethrough's flanking
+ *     rule (`micromark-extension-gfm-strikethrough`, which is CommonMark's
+ *     `*` rule without the underscore exception): classify the character on
+ *     each side as whitespace, punctuation, or other, then
+ *
+ *         open  = after is not whitespace and (after is not punctuation or before is whitespace/punctuation)
+ *         close = before is not whitespace and (before is not punctuation or after is whitespace/punctuation)
+ *
+ *     So `++text++` behaves the way `~~text~~` and `**text**` already do:
+ *     `i++; j++;` and `C++` stay literal (a run before punctuation after a
+ *     letter cannot open), `word++x++word` DOES underline (intraword, like
+ *     `~~`), `see ++(note)++ here` underlines but `a++(note)++b` does not.
+ *     Whitespace = end of input, line endings, tabs, spaces, Unicode
+ *     whitespace; punctuation = Unicode P and S. micromark hands over UTF-16
+ *     code units, so an astral character (an emoji) arrives as two surrogates
+ *     and classifies as "other", exactly as it does for `~~`.
+ *   • Exactly two markers. A lone `+`, a `+++` run, an unclosed `++text`, a
+ *     closer with no opener, spaces just inside the markers — all stay
+ *     literal text. Nothing is dropped and nothing throws (D3 rule 3).
+ *   • Code spans and fences are untouched: micromark never runs text
+ *     constructs inside them, so `` `++x++` `` shows the plus signs.
+ *   • `\++` is an ordinary character escape and stays literal.
+ *   • Registered as an `insideSpan` resolver AND an attention marker — the
+ *     same two hooks strikethrough uses — so `**++x++**`, `++**x**++`,
+ *     `~~++x++~~` and the intraword `a**++x++**b` all nest correctly.
+ *   • Two pairs CAN nest structurally (`++a ++b++ c++` → `<u>a <u>b</u> c</u>`),
+ *     exactly as `~~` does. The composer never emits that (a mark cannot
+ *     nest in ProseMirror) and it renders as one underline, so it is pinned
+ *     rather than prevented.
+ */
+
+// ---------------------------------------------------------------------------
+// Local structural types — mirrors of `micromark-util-types` (see header).
+// Only the members this construct touches are declared.
+// ---------------------------------------------------------------------------
+
+/**
+ * A character code. `null` is end of input; negative values are micromark's
+ * virtual characters (line endings, tab expansion); everything else is a
+ * Unicode code point.
+ */
+type Code = number | null
+
+interface Point {
+  line: number
+  column: number
+  offset: number
+  _index: number
+  _bufferIndex: number
+}
+
+interface Token {
+  type: string
+  start: Point
+  end: Point
+  _open?: boolean
+  _close?: boolean
+}
+
+interface Resolvable {
+  readonly resolveAll?: Resolver | undefined
+}
+
+interface TokenizeContext {
+  readonly previous: Code
+  readonly events: Event[]
+  readonly parser: {
+    readonly constructs: {
+      readonly insideSpan: { readonly null?: readonly Resolvable[] | undefined }
+    }
+  }
+}
+
+type Event = ['enter' | 'exit', Token, TokenizeContext]
+type State = (code: Code) => State | undefined
+type Resolver = (events: Event[], context: TokenizeContext) => Event[]
+type Tokenizer = (this: TokenizeContext, effects: Effects, ok: State, nok: State) => State
+
+interface Effects {
+  enter(type: string): Token
+  exit(type: string): Token
+  consume(code: Code): undefined
+}
+
+interface Construct extends Resolvable {
+  readonly name: string
+  readonly tokenize: Tokenizer
+  readonly resolveAll: Resolver
+}
+
+/** The three hooks a micromark syntax extension may register for an inline construct. */
+interface MicromarkExtension {
+  readonly text: Readonly<Record<number, Construct>>
+  readonly insideSpan: { readonly null: readonly Construct[] }
+  readonly attentionMarkers: { readonly null: readonly Code[] }
+}
+
+// Mirrors of `mdast-util-from-markdown` — the compile side.
+
+/**
+ * The mdast node. `data.hName` is the documented `mdast-util-to-hast` hook:
+ * an unknown node type with an `hName` becomes an element of that name, so
+ * no rehype plugin of any kind is involved and the raw-HTML ban is untouched.
+ */
+interface UnderlineNode {
+  type: 'underline'
+  children: unknown[]
+  data: { hName: 'u' }
+}
+
+interface CompileContext {
+  enter(node: UnderlineNode, token: Token): undefined
+  exit(token: Token): undefined
+}
+
+type Handle = (this: CompileContext, token: Token) => undefined
+
+interface FromMarkdownExtension {
+  readonly canContainEols: readonly string[]
+  readonly enter: Readonly<Record<string, Handle>>
+  readonly exit: Readonly<Record<string, Handle>>
+}
+
+// The slice of a unified processor the plugin touches. `settings` is listed
+// so the type is not "weak" (all-optional) and unified's `Data` — which has
+// `settings` — is assignable to it whether or not remark-parse's augmentation
+// (`micromarkExtensions` / `fromMarkdownExtensions`) is loaded in a consumer.
+interface RemarkData {
+  settings?: unknown
+  micromarkExtensions?: unknown[]
+  fromMarkdownExtensions?: unknown[]
+}
+
+interface RemarkProcessorLike {
+  data(): RemarkData
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** U+002B PLUS SIGN. */
+const PLUS = 43
+/** U+0020 SPACE. */
+const SPACE = 32
+
+const SEQUENCE_TEMPORARY = 'underlineSequenceTemporary'
+const SEQUENCE = 'underlineSequence'
+const UNDERLINE = 'underline'
+const UNDERLINE_TEXT = 'underlineText'
+/** micromark's own token types this construct reads. */
+const CHARACTER_ESCAPE = 'characterEscape'
+const DATA = 'data'
+
+/** `Array#splice` spreads its items as arguments; past this many V8 overflows the stack. */
+const SPLICE_CHUNK = 10_000
+
+/** `micromark-util-character`'s `unicodeWhitespace` / `unicodePunctuation`. */
+const UNICODE_WHITESPACE = /\s/
+const UNICODE_PUNCTUATION = /\p{P}|\p{S}/u
+
+/** `micromark-util-symbol`'s character groups. */
+const GROUP_WHITESPACE = 1
+const GROUP_PUNCTUATION = 2
+type CharacterGroup = typeof GROUP_WHITESPACE | typeof GROUP_PUNCTUATION | undefined
+
+// ---------------------------------------------------------------------------
+// Re-derived helpers (see header for why these are not imports)
+// ---------------------------------------------------------------------------
+
+/**
+ * `micromark-util-classify-character`: whitespace (end of input, any virtual
+ * character — all line endings and tab parts are negative codes — the space,
+ * Unicode whitespace), punctuation (Unicode P and S), or other. Codes are
+ * UTF-16 units and are stringified with `fromCharCode` exactly as micromark's
+ * `regexCheck` does, so surrogate halves classify as "other" here too.
+ */
+function classifyCharacter(code: Code): CharacterGroup {
+  if (code === null || code < 0 || code === SPACE) return GROUP_WHITESPACE
+  const character = String.fromCharCode(code)
+  if (UNICODE_WHITESPACE.test(character)) return GROUP_WHITESPACE
+  if (UNICODE_PUNCTUATION.test(character)) return GROUP_PUNCTUATION
+  return undefined
+}
+
+/** `micromark-util-chunked`'s `splice`: `Array#splice` that survives huge item lists. */
+function spliceChunked<T>(list: T[], start: number, remove: number, items: readonly T[]): void {
+  const end = list.length
+  let at = start < 0 ? (-start > end ? 0 : end + start) : start > end ? end : start
+  const count = remove > 0 ? remove : 0
+
+  if (items.length < SPLICE_CHUNK) {
+    list.splice(at, count, ...items)
+    return
+  }
+
+  if (count > 0) list.splice(at, count)
+  let from = 0
+  while (from < items.length) {
+    list.splice(at, 0, ...items.slice(from, from + SPLICE_CHUNK))
+    from += SPLICE_CHUNK
+    at += SPLICE_CHUNK
+  }
+}
+
+/** `micromark-util-resolve-all`: run each distinct `resolveAll` once, in order. */
+function resolveAll(
+  constructs: readonly Resolvable[],
+  events: Event[],
+  context: TokenizeContext,
+): Event[] {
+  const called: Resolver[] = []
+  let result = events
+  for (const construct of constructs) {
+    const resolve = construct.resolveAll
+    if (resolve !== undefined && !called.includes(resolve)) {
+      result = resolve(result, context)
+      called.push(resolve)
+    }
+  }
+  return result
+}
+
+// ---------------------------------------------------------------------------
+// The micromark construct
+// ---------------------------------------------------------------------------
+
+/**
+ * Tokenize one `++` run. Runs whenever the text tokenizer meets a `+`.
+ * Emits a temporary sequence token flagged with whether it may open and/or
+ * close; the resolver pairs them afterwards.
+ */
+function tokenizeUnderline(
+  this: TokenizeContext,
+  effects: Effects,
+  ok: State,
+  nok: State,
+): State {
+  const previous = this.previous
+  const events = this.events
+  let size = 0
+
+  return start
+
+  function start(code: Code): State | undefined {
+    // A `+` directly after another `+` that was not an escape means we are
+    // inside a run an earlier attempt already rejected (`+++`): stay literal.
+    if (previous === PLUS && events[events.length - 1]?.[1].type !== CHARACTER_ESCAPE) {
+      return nok(code)
+    }
+    effects.enter(SEQUENCE_TEMPORARY)
+    return more(code)
+  }
+
+  function more(code: Code): State | undefined {
+    if (code === PLUS) {
+      // A third marker is not this syntax.
+      if (size > 1) return nok(code)
+      effects.consume(code)
+      size++
+      return more
+    }
+    if (size < 2) return nok(code)
+
+    const token = effects.exit(SEQUENCE_TEMPORARY)
+    // GFM strikethrough's flanking rule, verbatim (see header).
+    const before = classifyCharacter(previous)
+    const after = classifyCharacter(code)
+    token._open = after === undefined || (after === GROUP_PUNCTUATION && before !== undefined)
+    token._close = before === undefined || (before === GROUP_PUNCTUATION && after !== undefined)
+    return ok(code)
+  }
+}
+
+/**
+ * Pair closers with the nearest earlier opener, wrapping the events between
+ * in `underline` / `underlineText`, and demote every sequence that did not
+ * pair to plain `data` so its characters render as typed.
+ */
+function resolveAllUnderline(events: Event[], context: TokenizeContext): Event[] {
+  let index = -1
+
+  while (++index < events.length) {
+    const closer = events[index]
+    if (
+      closer === undefined ||
+      closer[0] !== 'enter' ||
+      closer[1].type !== SEQUENCE_TEMPORARY ||
+      closer[1]._close !== true
+    ) {
+      continue
+    }
+
+    let open = index
+    while (open--) {
+      const opener = events[open]
+      if (
+        opener === undefined ||
+        opener[0] !== 'exit' ||
+        opener[1].type !== SEQUENCE_TEMPORARY ||
+        opener[1]._open !== true ||
+        // Sizes must match — always two here, kept for parity with the model.
+        closer[1].end.offset - closer[1].start.offset !==
+          opener[1].end.offset - opener[1].start.offset
+      ) {
+        continue
+      }
+
+      closer[1].type = SEQUENCE
+      opener[1].type = SEQUENCE
+
+      const underline: Token = {
+        type: UNDERLINE,
+        start: { ...opener[1].start },
+        end: { ...closer[1].end },
+      }
+      const text: Token = {
+        type: UNDERLINE_TEXT,
+        start: { ...opener[1].end },
+        end: { ...closer[1].start },
+      }
+
+      // Opening.
+      const next: Event[] = [
+        ['enter', underline, context],
+        ['enter', opener[1], context],
+        ['exit', opener[1], context],
+        ['enter', text, context],
+      ]
+
+      // Between — let every other span construct (emphasis, strong,
+      // strikethrough, this one again) resolve inside the pair.
+      const insideSpan = context.parser.constructs.insideSpan.null
+      if (insideSpan !== undefined) {
+        spliceChunked(
+          next,
+          next.length,
+          0,
+          resolveAll(insideSpan, events.slice(open + 1, index), context),
+        )
+      }
+
+      // Closing.
+      spliceChunked(next, next.length, 0, [
+        ['exit', text, context],
+        ['enter', closer[1], context],
+        ['exit', closer[1], context],
+        ['exit', underline, context],
+      ])
+
+      spliceChunked(events, open - 1, index - open + 3, next)
+      index = open + next.length - 2
+      break
+    }
+  }
+
+  // Whatever did not pair is text. Never dropped, never thrown (D3 rule 3).
+  for (const event of events) {
+    if (event[1].type === SEQUENCE_TEMPORARY) event[1].type = DATA
+  }
+
+  return events
+}
+
+function underlineSyntax(): MicromarkExtension {
+  const construct: Construct = {
+    name: 'underline',
+    tokenize: tokenizeUnderline,
+    resolveAll: resolveAllUnderline,
+  }
+  return {
+    text: { [PLUS]: construct },
+    insideSpan: { null: [construct] },
+    attentionMarkers: { null: [PLUS] },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The mdast compile extension
+// ---------------------------------------------------------------------------
+
+function enterUnderline(this: CompileContext, token: Token): undefined {
+  this.enter({ type: UNDERLINE, children: [], data: { hName: 'u' } }, token)
+}
+
+function exitUnderline(this: CompileContext, token: Token): undefined {
+  this.exit(token)
+}
+
+function underlineFromMarkdown(): FromMarkdownExtension {
+  return {
+    // A soft line break inside `++a\nb++` is kept as text, like `delete`.
+    canContainEols: [UNDERLINE],
+    enter: { [UNDERLINE]: enterUnderline },
+    exit: { [UNDERLINE]: exitUnderline },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The remark plugin
+// ---------------------------------------------------------------------------
+
+/**
+ * remark plugin: `++text++` → `<u>`. Register after `remarkGfm` in a
+ * `remarkPlugins` list. Same shape as `remark-gfm` itself — it appends one
+ * micromark syntax extension and one mdast compile extension to the
+ * processor's data and returns nothing.
+ */
+export function remarkUnderline(this: RemarkProcessorLike): undefined {
+  const data = this.data()
+  const micromark = data.micromarkExtensions ?? (data.micromarkExtensions = [])
+  const fromMarkdown = data.fromMarkdownExtensions ?? (data.fromMarkdownExtensions = [])
+  micromark.push(underlineSyntax())
+  fromMarkdown.push(underlineFromMarkdown())
+}