feat(instructions): improve example styles, update specs, support instruction doc links (#144)

Author: i582

src/features/spec/gen/tvm-specification.json

@@ -25,6 +25,11 @@ export interface Instruction {
   readonly control_flow?: ControlFlowOfInstruction
 }
 
+export interface GasConsumptionEntry {
+  readonly value: number
+  readonly description: string
+}
+
 export enum Category {
   Arithmetic = "arithmetic",
   Cell = "cell",
@@ -61,31 +66,46 @@ export enum SubCategory {
   Tuple = "tuple",
 }
 
+export interface ExitCode {
+  readonly errno: string
+  readonly condition: string
+}
+
+export interface ExampleInstruction {
+  readonly instruction: string
+  readonly comment?: string
+  readonly is_main?: boolean
+}
+
+export interface ExampleStack {
+  readonly input: readonly string[]
+  readonly output: readonly string[]
+}
+
+export interface Example {
+  readonly instructions: readonly ExampleInstruction[]
+  readonly stack: ExampleStack
+  readonly exit_code?: number
+}
+
 export interface Description {
-  short: string
-  long: string
-  doc_links?: DocLinks
-  tags?: Tag[]
-  exit_codes?: Array<{errno: string; condition: string}>
-  examples?: Array<{
-    instructions: Array<{instruction: string; comment?: string; is_main?: boolean}>
-    stack: {input: string[]; output: string[]}
-    exit_code?: number
-    other_implementations?: {
-      exact: boolean
-      instructions: string[]
-    }[]
-  }>
-  other_implementations?: {
-    exact: boolean
-    instructions: string[]
+  readonly short: string
+  readonly long: string
+  readonly tags?: Tag[]
+  readonly exit_codes?: ExitCode[]
+  readonly examples?: Example[]
+  readonly other_implementations?: {
+    readonly exact: boolean
+    readonly instructions: string[]
   }[]
-  operands: string[]
+  readonly operands: readonly string[]
+  readonly gas?: readonly GasConsumptionEntry[]
+  readonly docs_links?: readonly DocsLink[]
 }
 
-export interface DocLinks {
-  "accept_message effects"?: string
-  "Low-level fees overview"?: string
+export interface DocsLink {
+  readonly name: string
+  readonly url: string
 }
 
 export enum Tag {

src/features/spec/tvm-specification.types.ts

@@ -207,6 +207,11 @@
   --table-code-bg-color: var(--color-background-input);
   --table-code-text-color: var(--color-text-primary);
 
+  /* Code syntax highlighting */
+  --syntax-keyword: #0033b3;
+  --syntax-number: #1750eb;
+  --syntax-comment: #8c8c8c;
+
   --tracepage-logo-main-color: #000000;
   --tracepage-logo-gradient-start: #4a69e0;
   --tracepage-logo-gradient-end: #3690fd;
@@ -412,6 +417,11 @@
   --table-code-bg-color: var(--color-background-input);
   --table-code-text-color: var(--color-text-primary);
 
+  /* Code syntax highlighting */
+  --syntax-keyword: #749ded;
+  --syntax-number: #b5cea8;
+  --syntax-comment: #6a9955;
+
   --tracepage-logo-main-color: var(--color-text-primary);
   --tracepage-logo-gradient-start: #4a69e0;
   --tracepage-logo-gradient-end: #3690fd;

src/index.css

@@ -27,7 +27,6 @@
   flex-direction: column;
   width: calc(100% - var(--spacing-sm) * 2);
   min-height: 0;
-  overflow: hidden;
   gap: var(--spacing-sm);
   padding: 0 var(--spacing-sm) var(--spacing-sm) var(--spacing-sm);
   flex-grow: 1;

src/pages/InstructionsPage/InstructionsPage.module.css

@@ -0,0 +1,124 @@
+.exampleItem {
+  margin-bottom: 0;
+  padding: var(--spacing-md);
+  border: 1px solid var(--color-border);
+  border-radius: var(--border-radius-md);
+  background-color: var(--background-color);
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+
+.exampleItemError {
+  background-color: var(--color-error-bg-light);
+}
+
+.exampleErrorHeader {
+  margin-bottom: var(--spacing-sm);
+  border-radius: calc(var(--border-radius-md) / 2);
+  color: var(--color-text-primary);
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-sm);
+  flex-wrap: wrap;
+}
+
+.errorIcon {
+  font-size: var(--font-size-lg);
+  color: #c62828;
+  display: flex;
+  align-items: center;
+}
+
+.errorConditionText {
+  margin: 0;
+  font-size: var(--font-size-sm);
+  color: var(--color-text-secondary);
+  width: 100%;
+  padding-top: var(--spacing-xs);
+}
+
+.errorConditionText p {
+  display: inline;
+  margin: 0;
+}
+
+.exampleInstructions {
+  margin-bottom: var(--spacing-sm);
+}
+
+.codeBlockContainer {
+  position: relative;
+}
+
+.codeBlock {
+  background-color: var(--color-background-secondary);
+  padding: var(--spacing-sm);
+  margin: 0 0 var(--spacing-sm) 0;
+  border-radius: calc(var(--border-radius-md) / 2);
+  font-family: var(--font-family-mono), monospace;
+  font-size: var(--font-size-sm);
+  overflow-x: scroll;
+  overflow-y: visible;
+  white-space: pre;
+}
+
+.codeBlock code {
+  font-family: inherit;
+  font-size: inherit;
+}
+
+.codeBlock .comment {
+  color: var(--color-text-tertiary);
+  font-style: italic;
+}
+
+.codeBlock .preparatoryComment {
+  color: var(--color-text-secondary);
+  font-style: italic;
+}
+
+.exampleStack {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: var(--spacing-md);
+}
+
+.exampleStructTitle {
+  margin: 0;
+  color: var(--color-text-secondary);
+}
+
+.preparatoryInstruction code {
+  color: var(--color-text-secondary);
+}
+
+.stackDisplayContainer {
+  margin-top: var(--spacing-xs);
+}
+
+.playgroundLink {
+  display: inline-flex;
+  /*position: absolute;*/
+  align-items: center;
+  gap: var(--spacing-sms);
+  color: var(--color-text-secondary) !important;
+  text-decoration: none;
+  font-size: var(--font-size-xs);
+  border-radius: var(--border-radius-sm);
+  transition: color var(--transition-duration-fast);
+  margin-top: var(--spacing-mds);
+  margin-bottom: -4px;
+  margin-left: 2px;
+  right: 0;
+  opacity: 0.7;
+}
+
+.playgroundLink:hover {
+  color: var(--color-text-primary) !important;
+  opacity: 0.8;
+}
+
+.playIcon {
+  font-size: var(--font-size-xss);
+}