From fb3d85487867879d9ad857e8c4ca72f056abdd26 Mon Sep 17 00:00:00 2001 From: "remy.baranx@gmail.com" Date: Tue, 5 Mar 2024 17:42:32 +0700 Subject: [PATCH] UX improvements after PR review --- components/LibFuncTable/DocRowDetail.tsx | 13 ++ components/LibFuncTable/index.tsx | 7 +- components/ui/Doc.tsx | 14 +- components/ui/MdxComponents/MemoryTable.tsx | 26 +++ .../ui/MdxComponents/PlaygroundLink.tsx | 16 ++ components/ui/MdxComponents/RefsTable.tsx | 26 +++ components/ui/MdxComponents/TableLayout.tsx | 11 ++ components/ui/MdxComponents/index.tsx | 4 + docs/libfuncs/array_append.mdx | 72 ++++++-- docs/libfuncs/array_get.mdx | 168 +++++++++++------- pages/libfuncs.tsx | 96 +++++++++- 11 files changed, 361 insertions(+), 92 deletions(-) create mode 100644 components/ui/MdxComponents/MemoryTable.tsx create mode 100644 components/ui/MdxComponents/PlaygroundLink.tsx create mode 100644 components/ui/MdxComponents/RefsTable.tsx create mode 100644 components/ui/MdxComponents/TableLayout.tsx create mode 100644 components/ui/MdxComponents/index.tsx diff --git a/components/LibFuncTable/DocRowDetail.tsx b/components/LibFuncTable/DocRowDetail.tsx index 9015012..353a6f1 100644 --- a/components/LibFuncTable/DocRowDetail.tsx +++ b/components/LibFuncTable/DocRowDetail.tsx @@ -6,6 +6,12 @@ import { GITHUB_REPO_URL } from 'util/constants' import { Button } from 'components/ui' import * as Doc from 'components/ui/Doc' +import { + MemoryTable, + TableLayout, + RefsTable, + PlaygroundLink, +} from 'components/ui/MdxComponents' const options = { mdxOptions: { @@ -28,6 +34,13 @@ const mdxComponents = { td: Doc.TD, a: Doc.A, pre: Doc.Pre, + MemoryTable, + TableLayout, + RefsTable, + PlaygroundLink, + Cell: (props: Doc.CellProps) => , + LeftCell: (props: Doc.CellProps) => , + Line: Doc.TR, } const DocRowDetail = ({ mdxContent }: { mdxContent: any }) => { diff --git a/components/LibFuncTable/index.tsx b/components/LibFuncTable/index.tsx index 17e224b..4cdcd54 100644 --- a/components/LibFuncTable/index.tsx +++ b/components/LibFuncTable/index.tsx @@ -20,7 +20,7 @@ import { } from 'react-table' import { ILibFuncDocs, ILibFuncDoc } from 'types' -import { Button } from 'components/ui' +import { H2, Button } from 'components/ui' import columnDefinition from './columns' import DocRowDetail from './DocRowDetail' @@ -271,7 +271,10 @@ const LibFuncTable = ({ docs }: { docs: ILibFuncDocs }) => { return ( <> -
+
+

+ Sierra LibFuncs +

diff --git a/components/ui/Doc.tsx b/components/ui/Doc.tsx index 534d87f..9555cd2 100644 --- a/components/ui/Doc.tsx +++ b/components/ui/Doc.tsx @@ -7,14 +7,15 @@ import Link from 'next/link' const EMPTY_MARK = '*' type Props = { - children: string | JSX.Element + children?: string | JSX.Element | JSX.Element[] } type LinkProps = { href?: string } & Props -type TdProps = { +export type CellProps = { + colSpan?: number align?: 'left' | 'center' | 'right' | 'justify' | 'char' | undefined } & Props @@ -54,9 +55,11 @@ export const THead: React.FC = ({ children }) => ( {children} ) -export const TH: React.FC = ({ children }) => { +export const TH: React.FC = ({ colSpan, align, children }) => { return ( {children} + +export const TD: React.FC = ({ colSpan, align, children }) => { return (
= ({ children }) => { ) } -export const TD: React.FC = ({ align, children }) => { +export const TR: React.FC = ({ children }) =>
= ({ children }: Props) => { + return ( + + + + Memory + + + + @ + + Value + + + {children} +
+ ) +} diff --git a/components/ui/MdxComponents/PlaygroundLink.tsx b/components/ui/MdxComponents/PlaygroundLink.tsx new file mode 100644 index 0000000..bd886ee --- /dev/null +++ b/components/ui/MdxComponents/PlaygroundLink.tsx @@ -0,0 +1,16 @@ +import React from 'react' + +type Props = { + href: string +} + +export const PlaygroundLink: React.FC = ({ href }: Props) => ( + + Reproduce in playground. + +) diff --git a/components/ui/MdxComponents/RefsTable.tsx b/components/ui/MdxComponents/RefsTable.tsx new file mode 100644 index 0000000..a02e9dd --- /dev/null +++ b/components/ui/MdxComponents/RefsTable.tsx @@ -0,0 +1,26 @@ +import React from 'react' + +import * as Doc from 'components/ui/Doc' + +type Props = { + title: string + children: JSX.Element[] +} + +export const RefsTable: React.FC = ({ title, children }: Props) => { + return ( + + + + {title} + + + + Parameter + Value + + + {children} +
+ ) +} diff --git a/components/ui/MdxComponents/TableLayout.tsx b/components/ui/MdxComponents/TableLayout.tsx new file mode 100644 index 0000000..7cb9a85 --- /dev/null +++ b/components/ui/MdxComponents/TableLayout.tsx @@ -0,0 +1,11 @@ +import React from 'react' + +type Props = { + children: JSX.Element[] +} + +export const TableLayout: React.FC = ({ children }: Props) => { + return ( +
{children}
+ ) +} diff --git a/components/ui/MdxComponents/index.tsx b/components/ui/MdxComponents/index.tsx new file mode 100644 index 0000000..6d4bfab --- /dev/null +++ b/components/ui/MdxComponents/index.tsx @@ -0,0 +1,4 @@ +export { MemoryTable } from './MemoryTable' +export { RefsTable } from './RefsTable' +export { TableLayout } from './TableLayout' +export { PlaygroundLink } from './PlaygroundLink' diff --git a/docs/libfuncs/array_append.mdx b/docs/libfuncs/array_append.mdx index adb7adc..68829e8 100644 --- a/docs/libfuncs/array_append.mdx +++ b/docs/libfuncs/array_append.mdx @@ -1,30 +1,70 @@ --- shortDescription: Appends an element to the end of an array. -invokeRefs: '[0] | [1]' -outputRefs: '[2]' +invokeRefs: 'array | element' +fallthroughBranch: 'array' --- -## Description +# Description Appends an element to the end of an array. -## Syntax +# Syntax -`array_append([0]: Array, [1]: T) -> ([2]: Array)` +``` +array_append([array]: Array, [element]: T) -> ([array]: Array) +``` -## Invoke Refs +# Invoke Refs -| Name | Description | Type | -| :---: | :-------------------- | :--------: | -| `[0]` | The array to update | `Array` | -| `[1]` | The element to append | `T` | +- `[array]`: the array to update (`Array`). +- `[element]`: the element to insert (`T`). -## Output Refs +# Output Refs -| Name | Description | Type | -| :---: | :---------------- | :--------: | -| `[2]` | The updated array | `Array` | +- `[array]`: the updated array (`Array`). -## Example +# Examples -`array_append([1], [2]) -> ([3]);` +Append the value `42` to the end of an array. + +``` +array_append([1], [2]) -> ([3]) +``` + + + + + 145 + 1 + + + 149 + 4 + + + 150 + 42 + + + + + + `array` + [1] + `@145, @149` + + + `element` + [2] + 42 + + + + + + `array` + [3] + `@145, @150` + + + diff --git a/docs/libfuncs/array_get.mdx b/docs/libfuncs/array_get.mdx index fbcca4f..e0bbbae 100644 --- a/docs/libfuncs/array_get.mdx +++ b/docs/libfuncs/array_get.mdx @@ -7,7 +7,7 @@ statementBranch: 'rangeCheck' # Description -Gets an array element at a given index, handling out-of-range scenarios with a Statement branch. +Gets an array element at a given index (_fallthrough_ branch) or handles out-of-range scenarios with a _Statement_ branch. # Syntax @@ -20,91 +20,125 @@ array_get([rangeCheck]: RangeCheck, [array]: Array, [index]: usize) { # Invoke Refs -| Name | Description | Type | -| :------------: | :------------------------------- | :----------: | -| `[rangeCheck]` | Internal RangeCheck | `RangeCheck` | -| `[array]` | The array to read | `Array` | -| `[index]` | The index of the element to read | `usize` | +- `[rangeCheck]`: internal RangCheck (`RangeCheck`). +- `[array]`: the array to read (`Array`). +- `[index]`: the index of the element to read (`usize`). # Output Refs ## Fallthrough Branch -| Name | Description | Type | -| :------------: | :--------------------------------------- | :----------: | -| `[rangeCheck]` | The updated RangeCheck | `RangeCheck` | -| `[element]` | A pointer to an element at a given index | `Box` | +- `[rangeCheck]`: the updated RangeCheck (`RangeCheck`). +- `[element]`: a pointer to an element at a given index (`Box`). ## Target Statement Branch -| Name | Description | Type | -| :------------: | :--------------------- | :----------: | -| `[rangeCheck]` | The updated RangeCheck | `RangeCheck` | +- `[rangeCheck]`: the updated RangeCheck (`RangeCheck`). # Examples ## Example 1 - Fallthrough branch -Reading the element at index 1 from an array of 4 elements. - -`array_get([rangeCheck], [array], [index]) { fallthrough([rangeCheck], [element]) 59([rangeCheck]) }` - -### Memory - -| | Value | -| :---: | :---: | -| `140` | 2 | -| `141` | 0 | -| `145` | 4 | -| `146` | 3 | -| `147` | 2 | -| `148` | 1 | - -### Invoke refs - -| Name | Value | -| :----------: | :------: | -| `rangeCheck` | 140 | -| `array` | 145, 149 | -| `index` | 1 | - -### Fallthrough Branch Output Refs - -| Name | Value | -| :----------: | :---: | -| `rangeCheck` | 141 | -| `element` | 146 | - -## Example 2 -Statement branch +Reading the element at index 1 from an array of 4 elements (`u32`). ``` -array_get([rangeCheck], [array], [index]) { - fallthrough([rangeCheck], [element]) - 59([rangeCheck]) +array_get([140], [141], [142]) { + fallthrough([144], [146]) + 59([144]) } ``` -### Memory + + + + 145 + 1 + + + 149 + 4 + + + + + + `rangeCheck` + [140] + 2 + + + `array` + [141] + `@145, @149` + + + `index` + [142] + 1 + + + + + + `rangeCheck` + [144] + 3 + + + `element` + [146] + `@145` + + + -| | Value | -| :---: | :---: | -| `140` | 2 | -| `141` | 0 | -| `145` | 4 | -| `146` | 3 | -| `147` | 2 | -| `148` | 1 | - -### Invoke refs +## Example 2 -Statement branch -| Name | Value | -| :----------: | :------: | -| `rangeCheck` | 140 | -| `array` | 145, 149 | -| `index` | 4 | +Reading the element at index 4 from an array of 4 elements (`u32`), leads to a jump to +the statement branch 59 because of an out-of-range error. -### Target Statement Branch Output Refs +``` +array_get([140], [141], [142]) { + fallthrough([144], [150]) + 59([144]) +} +``` -| Name | Value | -| :----------: | :---: | -| `rangeCheck` | 141 | + + + + 145 + 1 + + + 149 + 4 + + + + + + `rangeCheck` + [140] + 2 + + + `array` + [141] + `@145, @149` + + + `index` + [142] + 4 + + + + + + `rangeCheck` + [144] + 3 + + + diff --git a/pages/libfuncs.tsx b/pages/libfuncs.tsx index 321aa8b..3712c9a 100644 --- a/pages/libfuncs.tsx +++ b/pages/libfuncs.tsx @@ -1,6 +1,9 @@ import fs from 'fs' import path from 'path' +import { useState, useEffect } from 'react' + +import { RiCloseLine } from '@remixicon/react' import matter from 'gray-matter' import type { NextPage } from 'next' import getConfig from 'next/config' @@ -12,11 +15,25 @@ import { ILibFuncDocs } from 'types' import ContributeBox from 'components/ContributeBox' import HomeLayout from 'components/layouts/Home' import LibFuncTable from 'components/LibFuncTable' -import { H1, Container } from 'components/ui' +import { H1, H2, Container } from 'components/ui' const { serverRuntimeConfig } = getConfig() const LibFuncPage = ({ libFuncDocs }: { libFuncDocs: ILibFuncDocs }) => { + const [showIntro, setShowIntro] = useState(false) + + useEffect(() => { + const isIntroClosed = localStorage.getItem('isIntroClosed') + if (!isIntroClosed) { + setShowIntro(true) + } + }, []) + + const handleCloseIntro = () => { + localStorage.setItem('isIntroClosed', 'closed') + setShowIntro(false) + } + return ( <> @@ -27,8 +44,81 @@ const LibFuncPage = ({ libFuncDocs }: { libFuncDocs: ILibFuncDocs }) => { content="Sierra LibFuncs Interactive Reference" /> - -

Sierra LibFuncs Interactive Reference

+ +

Sierra LibFuncs - Interactive Reference

+ + {showIntro && ( + <> +
+

Introduction

+ +
+
+

+ Sierra is + an intermediate language built as a stable layer between{' '} + Cairo, a + high-level language, and{' '} + CASM, the + instruction set of the Cairo VM. +

+

+ Sierra statements are constructed using a fixed set of functions + called{' '} + Libfuncs. + These functions follow a specific format:{' '} + {`() -> ()`} +

+

+ The input parameters are referred to as{' '} + Invoke Refs{' '} + while the output parameters are referred to as{' '} + Output Refs + . Both are{' '} + references, + represented by a numeric value in brackets, such as{' '} + [140]. +

+

+ A single reference always refers to the same variable throughout + the program's execution. Each variable's value associated with a + reference is a set of one or more felt252 values. +

+

+ Sierra also employs a specific syntax for handling output + branches: the{' '} + falltrough{' '} + branch is used when the function execution is successful while a + failure branch can be specified using a{' '} + + StatementIdx + {' '} + which is the numerical index of the statement to jump to in case + of failure. +

+

+ The complete format for this type of libfunc is: +

+ 
+                {`() {
+  fallthrough()
+  StatementIdx()
+}`}
+
+

+ Note that in the following documentation, an integer value is + represented by a numeric value like 10 while an + address is represented using a @ like{' '} + @10. +

+
+ + )}