react-native-marcus 0.1.1 → 0.2.0

package/lib/commonjs/MarcusTextDecoratorViewNativeComponent.ts

@@ -0,0 +1,199 @@
+import { codegenNativeComponent } from "react-native"
+import type { ColorValue, ViewProps } from "react-native"
+
+import type { Float, Int32 } from "react-native/Libraries/Types/CodegenTypes"
+
+import type { MarkdownStyle as TextInputMarkdownStyle } from "./MarcusTextInputDecoratorViewNativeComponent"
+
+// Codegen parses each `*NativeComponent` file on its own and does not follow
+// imports, so the style has to be spelled out again rather than shared with
+// `MarcusTextInputDecoratorViewNativeComponent`. The assertion further down is
+// what keeps the copy honest: the two have to stay assignable in both
+// directions or `tsc --noEmit` fails.
+
+// The text attributes one styled run can carry: the subset of React Native's
+// `TextStyle` that survives as an `NSAttributedString` attribute on iOS, as a
+// span on Android, and as a declaration on an inline element on the web.
+//
+// Everything here is optional and everything unset is inherited, which is what a
+// run of markdown wants -- a mention that only names a colour keeps the face,
+// the size and the weight of the prose it sits in. Native reads "unset" off the
+// zero value: an empty string, a null colour, a zero length. That costs nothing,
+// because a zero-length `letterSpacing`, `lineHeight` or `fontSize` means the
+// same as leaving it out.
+//
+// `fontWeight`, `fontStyle`, `textDecorationLine` and `textDecorationStyle`
+// arrive as plain strings rather than as unions. Codegen turns a union of string
+// literals into an enum named after the prop it was found on, so the same
+// spelling on twelve entries would become twelve unrelated C++ types and the one
+// conversion template in `RCTMarcusStyle+Codegen.h` could not read any of them.
+// The public type in `styleUtils` is the narrow one; this is the wire.
+interface MarkdownTextStyle {
+  color?: ColorValue
+  fontFamily?: string
+  fontSize?: Float
+  fontStyle?: string
+  fontWeight?: string
+  letterSpacing?: Float
+  // Applies to whole lines: the platforms set it on the paragraph, so a range
+  // covering part of a line raises the height of all of it.
+  lineHeight?: Float
+  textDecorationLine?: string
+  // iOS and web only. Android draws an underline and a strikethrough in the text
+  // colour and offers no way to say otherwise.
+  textDecorationColor?: ColorValue
+  textDecorationStyle?: string
+  textShadowColor?: ColorValue
+  textShadowOffset?: { width: Float; height: Float }
+  textShadowRadius?: Float
+}
+
+// A run drawn as a box rather than as a background behind the glyphs: an inline
+// or fenced run of code, or a mention's pill. Rounded, optionally bordered, with
+// room inside it and around it, on top of whatever text attributes it carries.
+//
+// What the room holds open differs, because a block owns its lines and a run
+// shares one. A block's padding and margin are held open on the leading edge and
+// vertically, and a line long enough to wrap reaches the padding on the trailing
+// edge rather than stopping in front of it: neither platform can reserve a
+// trailing indent per paragraph. An inline run holds its padding and margin open
+// on both sides, by widening the characters it starts and ends with, and grows
+// into the line's own spacing above and below rather than pushing the lines
+// apart.
+//
+// `padding` is the fallback for both axes; `paddingHorizontal` and
+// `paddingVertical` win over it where they are set, and `margin` the same. A
+// fenced block usually wants more room above and below than beside it, and one
+// number cannot say that.
+interface MarkdownBoxStyle extends MarkdownTextStyle {
+  backgroundColor?: ColorValue
+  borderColor?: ColorValue
+  borderWidth?: Float
+  borderRadius?: Float
+  padding?: Float
+  paddingHorizontal?: Float
+  paddingVertical?: Float
+  margin?: Float
+  marginHorizontal?: Float
+  marginVertical?: Float
+}
+
+interface MarkdownHeadingStyle extends MarkdownTextStyle {
+  // Each level down multiplies the one above, so level N is
+  // fontSize * scale^(N - 1). Six levels, matching HTML.
+  scale?: Float
+}
+
+// The bar beside a quoted block, the indent it opens, and the text inside it.
+//
+// `marginStart` and `paddingStart` rather than `marginLeft`/`paddingLeft`
+// because the gutter opens on the line's leading edge, which is the right-hand
+// side of a right-to-left paragraph. Both platforms already indent from the
+// leading edge -- `NSParagraphStyle`'s head indent and Android's leading margin
+// are both writing-direction relative -- so the names now say what was always
+// drawn, and the web builder resolves them to `padding-inline-start`.
+interface MarkdownBlockquoteStyle extends MarkdownTextStyle {
+  borderColor?: ColorValue
+  borderWidth?: Float
+  // Rounds the bar's ends. A bar whose radius is half its width comes out a
+  // capsule.
+  borderRadius?: Float
+  marginStart?: Float
+  paddingStart?: Float
+}
+
+// Indent, and the marker that sits in the gutter it opens. Kept as two separate
+// entries so a renderer can style ordered and unordered lists differently, which
+// is exactly what `markerScale` ends up meaning: an ordered item's number is
+// text, an unordered item's bullet is a shape.
+//
+// Both markers are sized from the base font -- the size the wrapped `Text`
+// renders at -- rather than from a size of their own, so a list marks itself in
+// proportion to the prose it marks however that prose is sized. `marker` styles
+// the marker itself, and what it leaves unset falls back to `syntax`, which is
+// where a marker's colour came from before this entry existed.
+//
+// Only `MarkdownText` draws them. An input shows the marker you typed, in the
+// base font, because it is text you are editing rather than a rendering of it.
+interface MarkdownListStyle {
+  marginStart?: Float
+  paddingStart?: Float
+  // An ordered item's number is drawn at this fraction of the base font size; an
+  // unordered item's bullet takes it as a diameter, as a fraction of the same.
+  markerScale?: Float
+  // Room held open either side of the marker, between the gutter and the text.
+  markerPadding?: Float
+  marker?: MarkdownTextStyle
+}
+
+// Left as the two values it always was rather than folded into
+// `MarkdownTextStyle`: an emoji run is swapped onto a font that has the glyph
+// and sized to sit with the prose, and nothing else about it is worth saying.
+interface MarkdownEmojiStyle {
+  fontSize?: Float
+  fontFamily?: string
+}
+
+interface MarkdownStyle {
+  syntax: MarkdownTextStyle
+  emoji: MarkdownEmojiStyle
+  link: MarkdownTextStyle
+  strong: MarkdownTextStyle
+  emphasis: MarkdownTextStyle
+  strikethrough: MarkdownTextStyle
+  heading: MarkdownHeadingStyle
+  blockquote: MarkdownBlockquoteStyle
+  orderedList: MarkdownListStyle
+  unorderedList: MarkdownListStyle
+  code: MarkdownBoxStyle
+  pre: MarkdownBoxStyle
+  // A name with an `@` in front of it, drawn as a pill: the same inline box an
+  // inline run of code sits in, and so the same lengths.
+  mention: MarkdownBoxStyle
+}
+
+// `MarkdownRange` with `depth` filled in: codegen has no optional numbers, and
+// the formatters read a missing depth as zero anyway.
+interface MarkdownRangeStruct {
+  type: string
+  start: Int32
+  length: Int32
+  depth: Int32
+}
+
+// What one placeholder character copies as. `index` is its offset in the
+// stripped text -- the same string the ranges are measured against -- and
+// `text` is the markdown it was written as, which is what the platform puts on
+// the clipboard in its place.
+interface MarkdownSubstitutionStruct {
+  index: Int32
+  text: string
+}
+
+interface NativeProps extends ViewProps {
+  markdownStyle: MarkdownStyle
+  // The parse result, already stripped of syntax and remapped onto the text the
+  // child `Text` is rendering. Unlike the input decorator there is no parser to
+  // register: a `Text`'s content only ever changes by a re-render, so JS always
+  // knows the string and can hand over finished ranges.
+  ranges: ReadonlyArray<MarkdownRangeStruct>
+  // Every drawing in the text, and the source it copies as. A view mounted in a
+  // `Text` is one U+FFFC in the string the platform lays out, and that is what
+  // both platforms would otherwise hand to the clipboard: an equation copies as
+  // an empty box. Only the display needs this -- an input has the source on the
+  // screen already, and copies it by doing nothing.
+  substitutions: ReadonlyArray<MarkdownSubstitutionStruct>
+}
+
+type Assignable<A extends B, B> = A
+
+type StyleMatchesTextInput = [
+  Assignable<MarkdownStyle, TextInputMarkdownStyle>,
+  Assignable<TextInputMarkdownStyle, MarkdownStyle>,
+]
+
+export default codegenNativeComponent<NativeProps>("MarcusTextDecoratorView", {
+  interfaceOnly: true,
+})
+
+export type { MarkdownRangeStruct, MarkdownSubstitutionStruct, StyleMatchesTextInput }

package/lib/commonjs/MarcusTextInputDecoratorViewNativeComponent.ts

@@ -3,66 +3,145 @@ import type { ColorValue, ViewProps } from "react-native"
 
 import type { Float, Int32 } from "react-native/Libraries/Types/CodegenTypes"
 
-// Font, colour and background, and nothing else: neither formatter draws a
-// border or reserves padding around a code run, so there is nothing to
-// configure.
-interface CodeBlockStyle {
-  fontFamily: string
-  fontSize: Float
-  color: ColorValue
-  backgroundColor: ColorValue
+// The text attributes one styled run can carry: the subset of React Native's
+// `TextStyle` that survives as an `NSAttributedString` attribute on iOS, as a
+// span on Android, and as a declaration on an inline element on the web.
+//
+// Everything here is optional and everything unset is inherited, which is what a
+// run of markdown wants -- a mention that only names a colour keeps the face,
+// the size and the weight of the prose it sits in. Native reads "unset" off the
+// zero value: an empty string, a null colour, a zero length. That costs nothing,
+// because a zero-length `letterSpacing`, `lineHeight` or `fontSize` means the
+// same as leaving it out.
+//
+// `fontWeight`, `fontStyle`, `textDecorationLine` and `textDecorationStyle`
+// arrive as plain strings rather than as unions. Codegen turns a union of string
+// literals into an enum named after the prop it was found on, so the same
+// spelling on twelve entries would become twelve unrelated C++ types and the one
+// conversion template in `RCTMarcusStyle+Codegen.h` could not read any of them.
+// The public type in `styleUtils` is the narrow one; this is the wire.
+interface MarkdownTextStyle {
+  color?: ColorValue
+  fontFamily?: string
+  fontSize?: Float
+  fontStyle?: string
+  fontWeight?: string
+  letterSpacing?: Float
+  // Applies to whole lines: the platforms set it on the paragraph, so a range
+  // covering part of a line raises the height of all of it.
+  lineHeight?: Float
+  textDecorationLine?: string
+  // iOS and web only. Android draws an underline and a strikethrough in the text
+  // colour and offers no way to say otherwise.
+  textDecorationColor?: ColorValue
+  textDecorationStyle?: string
+  textShadowColor?: ColorValue
+  textShadowOffset?: { width: Float; height: Float }
+  textShadowRadius?: Float
+}
+
+// A run drawn as a box rather than as a background behind the glyphs: an inline
+// or fenced run of code, or a mention's pill. Rounded, optionally bordered, with
+// room inside it and around it, on top of whatever text attributes it carries.
+//
+// What the room holds open differs, because a block owns its lines and a run
+// shares one. A block's padding and margin are held open on the leading edge and
+// vertically, and a line long enough to wrap reaches the padding on the trailing
+// edge rather than stopping in front of it: neither platform can reserve a
+// trailing indent per paragraph. An inline run holds its padding and margin open
+// on both sides, by widening the characters it starts and ends with, and grows
+// into the line's own spacing above and below rather than pushing the lines
+// apart.
+//
+// `padding` is the fallback for both axes; `paddingHorizontal` and
+// `paddingVertical` win over it where they are set, and `margin` the same. A
+// fenced block usually wants more room above and below than beside it, and one
+// number cannot say that.
+interface MarkdownBoxStyle extends MarkdownTextStyle {
+  backgroundColor?: ColorValue
+  borderColor?: ColorValue
+  borderWidth?: Float
+  borderRadius?: Float
+  padding?: Float
+  paddingHorizontal?: Float
+  paddingVertical?: Float
+  margin?: Float
+  marginHorizontal?: Float
+  marginVertical?: Float
+}
+
+interface MarkdownHeadingStyle extends MarkdownTextStyle {
+  // Each level down multiplies the one above, so level N is
+  // fontSize * scale^(N - 1). Six levels, matching HTML.
+  scale?: Float
+}
+
+// The bar beside a quoted block, the indent it opens, and the text inside it.
+//
+// `marginStart` and `paddingStart` rather than `marginLeft`/`paddingLeft`
+// because the gutter opens on the line's leading edge, which is the right-hand
+// side of a right-to-left paragraph. Both platforms already indent from the
+// leading edge -- `NSParagraphStyle`'s head indent and Android's leading margin
+// are both writing-direction relative -- so the names now say what was always
+// drawn, and the web builder resolves them to `padding-inline-start`.
+interface MarkdownBlockquoteStyle extends MarkdownTextStyle {
+  borderColor?: ColorValue
+  borderWidth?: Float
+  // Rounds the bar's ends. A bar whose radius is half its width comes out a
+  // capsule.
+  borderRadius?: Float
+  marginStart?: Float
+  paddingStart?: Float
+}
+
+// Indent, and the marker that sits in the gutter it opens. Kept as two separate
+// entries so a renderer can style ordered and unordered lists differently, which
+// is exactly what `markerScale` ends up meaning: an ordered item's number is
+// text, an unordered item's bullet is a shape.
+//
+// Both markers are sized from the base font -- the size the wrapped `Text`
+// renders at -- rather than from a size of their own, so a list marks itself in
+// proportion to the prose it marks however that prose is sized. `marker` styles
+// the marker itself, and what it leaves unset falls back to `syntax`, which is
+// where a marker's colour came from before this entry existed.
+//
+// Only `MarkdownText` draws them. An input shows the marker you typed, in the
+// base font, because it is text you are editing rather than a rendering of it.
+interface MarkdownListStyle {
+  marginStart?: Float
+  paddingStart?: Float
+  // An ordered item's number is drawn at this fraction of the base font size; an
+  // unordered item's bullet takes it as a diameter, as a fraction of the same.
+  markerScale?: Float
+  // Room held open either side of the marker, between the gutter and the text.
+  markerPadding?: Float
+  marker?: MarkdownTextStyle
+}
+
+// Left as the two values it always was rather than folded into
+// `MarkdownTextStyle`: an emoji run is swapped onto a font that has the glyph
+// and sized to sit with the prose, and nothing else about it is worth saying.
+interface MarkdownEmojiStyle {
+  fontSize?: Float
+  fontFamily?: string
 }
 
 interface MarkdownStyle {
-  syntax: {
-    color: ColorValue
-  }
-  emoji: {
-    fontSize: Float
-    fontFamily: string
-  }
-  link: {
-    color: ColorValue
-  }
-  heading: {
-    fontSize: Float
-    // Each level down multiplies the one above, so level N is
-    // fontSize * scale^(N - 1). Six levels, matching HTML.
-    scale: Float
-  }
-  blockquote: {
-    borderColor: ColorValue
-    borderWidth: Float
-    marginLeft: Float
-    paddingLeft: Float
-  }
-  // Indent only, no gutter decoration. Kept as two separate entries so a
-  // renderer can style ordered and unordered lists differently.
-  orderedList: {
-    marginLeft: Float
-    paddingLeft: Float
-  }
-  unorderedList: {
-    marginLeft: Float
-    paddingLeft: Float
-  }
-  code: CodeBlockStyle
-  pre: CodeBlockStyle
-  mentionHere: {
-    color: ColorValue
-    backgroundColor: ColorValue
-    borderRadius?: Float
-  }
-  mentionUser: {
-    color: ColorValue
-    backgroundColor: ColorValue
-    borderRadius?: Float
-  }
-  mentionReport: {
-    color: ColorValue
-    backgroundColor: ColorValue
-    borderRadius?: Float
-  }
+  syntax: MarkdownTextStyle
+  emoji: MarkdownEmojiStyle
+  link: MarkdownTextStyle
+  strong: MarkdownTextStyle
+  emphasis: MarkdownTextStyle
+  strikethrough: MarkdownTextStyle
+  heading: MarkdownHeadingStyle
+  blockquote: MarkdownBlockquoteStyle
+  orderedList: MarkdownListStyle
+  unorderedList: MarkdownListStyle
+  code: MarkdownBoxStyle
+  pre: MarkdownBoxStyle
+  // A name with an `@` in front of it, drawn as a pill: the same inline box an
+  // inline run of code sits in, and so the same lengths.
+  mention: MarkdownBoxStyle
 }
 
 interface NativeProps extends ViewProps {
@@ -74,4 +153,12 @@ export default codegenNativeComponent<NativeProps>("MarcusTextInputDecoratorView
   interfaceOnly: true,
 })
 
-export type { MarkdownStyle }
+export type {
+  MarkdownStyle,
+  MarkdownTextStyle,
+  MarkdownEmojiStyle,
+  MarkdownBoxStyle,
+  MarkdownHeadingStyle,
+  MarkdownBlockquoteStyle,
+  MarkdownListStyle,
+}