diff --git a/README.md b/README.md index 6ee003d5..1f05fc3b 100644 --- a/README.md +++ b/README.md @@ -156,12 +156,13 @@ We support importing designs from Figma with our [figma-sdk](https://github.com/ ## Usage -Linting -Custom Tokenizer -Custom Assets Repository -Custom Cache -Custom Cursor -Plugins +- [REST API](./www/README.md) +- Linting (coming soon) +- Custom Tokenizer (coming soon) +- Custom Assets Repository (coming soon) +- Custom Cache (coming soon) +- Custom Cursor (coming soon) +- Plugins (coming soon) ### Running locally diff --git a/api/README.md b/api/README.md deleted file mode 100644 index aa2fe44c..00000000 --- a/api/README.md +++ /dev/null @@ -1,155 +0,0 @@ -# Grida Code API (Private Beta) - -## Usage (REST) - -### `POST /api/v1/code` - -Example - -```ts -import Axios from "axios"; - -const client = Axios.create({ - baseURL: "https://code.grida.co/api/v1", - headers: { - "Content-Type": "application/json", - "X-Figma-Access-Token": "figd_xxxxxxxxxx", - }, -}); - -client.post("code", { - // target node url formatted as https://www.figma.com/file/{fileKey}?node-id={nodeId} - // at this moment, the nodeId must be formatted as 00:00, not 00-00 - // Note: if you copy & paste the link from the fihma editor, you will get in the format of 00-00 (we are updating this) - figma: "https://www.figma.com/file/MikewnarPfXXXXX/?node-id=0%3A1", - framework: { - framework: "vanilla", // react, flutter, ... - }, -}); -``` - -#### Request Body - -```ts -interface CodeRequest { - figma: FigmaNodeInput; - framework: Partial; -} -``` - -**`body.figma`** - -```ts -type FigmaNodeInput = - | string - | { url: string; version: string } - | { filekey: string; node: string; version: string }; -``` - -**Note** currently only `string` is supported. - -An URL indicating the target node in Figma design. - -target node url formatted as `https://www.figma.com/file/{fileKey}?node-id={nodeId}` -at this moment, the nodeId must be formatted as `00:00`, not `00-00` url encoded value like `0%3A1` is also acceptable. - -Note: if you copy & paste the link from the fihma editor, you will get in the format of 00-00 (we are updating this) - -**`body.framework`** - -A Framework configuration used for generating code. Learn more at [Framework Configuration](https://grida.co/docs/cli#2-framework-configuration) - -#### Response - -```ts -// example of response -{ - warnings: [], - src: '', // do not use this - srcdoc: '......', - srcmap: { - // the mapping between the generated code and the design - // node-id : xpath - '123:123': '//div[@data-figma-node-id="123:123"]]' - }, - files:{ - 'index.hml': '......' - } - framework:{ - // the framework config used for generating code - // ... - }, - // (if the input design source is figma, you will get the brief summary about the used design) - figma:{ - file:{ - // #region original data ------ - name: "Exmaples", - lastModified: "2023-03-28T17:51:08Z", - thumbnailUrl: "https://s3-alpha.figma.com/thumbnails/dc85b86a-2502-4baa-a776-ce0972131a80", - version: "3247308401", - // #endregion original data ------ - } - - filekey: 'MikewnarPfXXXXX', - entry: '0:1', - json: "{}", - node: { - ... - } - } - engine: { - // the info of the engine used for generating code - name: 'code.grida.co/api/v1', - // the engibe version - version: '2023.1.1' - }, - // the preview image of the rendered html - thumbnail: 'https://xxx.s3.amazonaws.com/.../xxxxxx.png', - license: { - // the license info of the generated code and the api - // ... - } -} -``` - -- `warnings` - An array of warnings. If there is no warning, it will be an empty array. (This is usually a warning caused by poor design, which can be ignored) -- `src` - The generated code as a uri, a publicly accessible html file endpoint. -- `srcdoc` - The generated code as a bundled and concatenated string, which can be used to embed the code directly into your website. - -### `GET /api/v1/embed` - -We also provide an experimental embed API for embedding the generated code directly into your website with an iframe. - -Example - -```html - -``` - -#### URL Parameters - -**`figma`** -Same as `/v1/code` API's `figma` parameter. - -**`fpat`** or **`fat`** - -- fpat: Figma Personal Access Token (starting with `figd_`) -- fat: Figma Access Token - -Warning: For security reasons, we highly recommend using the Figma Access Token (which expires), instead of the Figma Personal Access Token (which never expires unless revoked). The Figma Personal Access Token is only used for development purpose. - -We are planning on providing a more secure way to use embed with the `fpat` in the future. - -The framework configuration for embed is `vanilla-preview` by default. We are planning on providing a way to customize the framework configuration in the future. - -## Request / Response Types Declarations - -See [./types.ts](./types.ts) - -## API Clients (Under Development) - -At this moment there is no publicly available API wrappers. If you are looking for use on your local machine, you van use [Grida CLI](https://grida.co/cli) diff --git a/api/__test__/.gitignore b/api/__test__/.gitignore deleted file mode 100644 index e69de29b..00000000 diff --git a/api/index.ts b/api/index.ts deleted file mode 100644 index d6fcf1a5..00000000 --- a/api/index.ts +++ /dev/null @@ -1,2 +0,0 @@ -export * from "./types"; -export * from "./license"; diff --git a/api/package.json b/api/package.json deleted file mode 100644 index a6389900..00000000 --- a/api/package.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "name": "@grida/api", - "version": "0.0.0" -} diff --git a/www/README.md b/www/README.md index c4033664..8a128862 100644 --- a/www/README.md +++ b/www/README.md @@ -1,36 +1,166 @@ -This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app). +# Grida Code API (Beta) - `code.api.grida.co` -## Getting Started +## Usage (REST) -First, run the development server: +### `POST /v1/code` -```bash -npm run dev -# or -yarn dev -# or -pnpm dev -# or -bun dev +Example + +```ts +import Axios from "axios"; + +const client = Axios.create({ + baseURL: "https://code.api.grida.co/v1", + headers: { + "Content-Type": "application/json", + "X-Figma-Access-Token": "figd_xxxxxxxxxx", + }, +}); + +client.post("code", { + // target node url formatted as https://www.figma.com/file/{fileKey}?node-id={nodeId} + // at this moment, the nodeId must be formatted as 00:00, not 00-00 + // Note: if you copy & paste the link from the fihma editor, you will get in the format of 00-00 (we are updating this) + figma: "https://www.figma.com/file/MikewnarPfXXXXX/?node-id=0%3A1", + framework: { + framework: "vanilla", // react, flutter, ... + }, +}); ``` -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. +#### Request Body + +```ts +interface CodeRequest { + figma: FigmaNodeInput; + framework: Partial; +} +``` + +**`body.figma`** -You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file. +```ts +type FigmaNodeInput = + | string + | { url: string; version: string } + | { filekey: string; node: string; version: string }; +``` + +**Note** currently only `string` is supported. + +An URL indicating the target node in Figma design. + +target node url formatted as `https://www.figma.com/file/{fileKey}?node-id={nodeId}` +at this moment, the nodeId must be formatted as `00:00`, not `00-00` url encoded value like `0%3A1` is also acceptable. + +Note: if you copy & paste the link from the fihma editor, you will get in the format of 00-00 (we are updating this) -This project uses [`next/font`](https://nextjs.org/docs/basic-features/font-optimization) to automatically optimize and load Inter, a custom Google Font. +**`body.framework`** -## Learn More +A Framework configuration used for generating code. Learn more at [Framework Configuration](https://grida.co/docs/cli#2-framework-configuration) -To learn more about Next.js, take a look at the following resources: +#### Response -- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. -- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. +```ts +// example of response +{ + warnings: [], + src: '', // do not use this + srcdoc: '......', + srcmap: { + // the mapping between the generated code and the design + // node-id : xpath + '123:123': '//div[@data-figma-node-id="123:123"]]' + }, + files:{ + 'index.hml': '......' + } + framework:{ + // the framework config used for generating code + // ... + }, + // (if the input design source is figma, you will get the brief summary about the used design) + figma:{ + file:{ + // #region original data ------ + name: "Exmaples", + lastModified: "2023-03-28T17:51:08Z", + thumbnailUrl: "https://s3-alpha.figma.com/thumbnails/dc85b86a-2502-4baa-a776-ce0972131a80", + version: "3247308401", + // #endregion original data ------ + } -You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome! + filekey: 'MikewnarPfXXXXX', + entry: '0:1', + json: "{}", + node: { + ... + } + } + engine: { + // the info of the engine used for generating code + name: 'code.api.grida.co/v1', + // the engibe version + version: '2023.1.1' + }, + // the preview image of the rendered html + thumbnail: 'https://xxx.s3.amazonaws.com/.../xxxxxx.png', + license: { + // the license info of the generated code and the api + // ... + } +} +``` + +- `warnings` - An array of warnings. If there is no warning, it will be an empty array. (This is usually a warning caused by poor design, which can be ignored) +- `src` - The generated code as a uri, a publicly accessible html file endpoint. +- `srcdoc` - The generated code as a bundled and concatenated string, which can be used to embed the code directly into your website. + +### `GET /v1/embed` -## Deploy on Vercel +We also provide an experimental embed API for embedding the generated code directly into your website with an iframe. -The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. +Example + +```html + +``` -Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details. +#### URL Parameters + +**`figma`** +Same as `/v1/code` API's `figma` parameter. + +**`fpat`** or **`fat`** + +- fpat: Figma Personal Access Token (starting with `figd_`) +- fat: Figma Access Token + +Warning: For security reasons, we highly recommend using the Figma Access Token (which expires), instead of the Figma Personal Access Token (which never expires unless revoked). The Figma Personal Access Token is only used for development purpose. + +We are planning on providing a more secure way to use embed with the `fpat` in the future. + +The framework configuration for embed is `vanilla-preview` by default. We are planning on providing a way to customize the framework configuration in the future. + +## Request / Response Types Declarations + +See [./types.ts](./types.ts) + +## API Clients (Under Development) + +At this moment there is no publicly available API wrappers. If you are looking for use on your local machine, you van use [Grida CLI](https://grida.co/cli) + +## Running Locally + +First, run the development server: + +```bash +yarn +yarn dev +``` + +Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. diff --git a/www/app/v1/code/route.ts b/www/app/v1/code/route.ts index 36ef07d2..84184f24 100644 --- a/www/app/v1/code/route.ts +++ b/www/app/v1/code/route.ts @@ -1,6 +1,6 @@ import { code } from "@grida/code"; -import type { CodeRequest, FigmaToVanillaResponse } from "@grida/api/types"; -import { LICENSE_CE } from "@grida/api"; +import { LICENSE_CE } from "@/license"; +import type { CodeRequest, FigmaToVanillaResponse } from "@/types"; import assert from "assert"; import { FrameworkConfig, VanillaFrameworkConfig } from "@grida/builder-config"; import { type NextRequest, NextResponse } from "next/server"; diff --git a/api/license.ts b/www/license.ts similarity index 100% rename from api/license.ts rename to www/license.ts diff --git a/api/types.ts b/www/types.ts similarity index 100% rename from api/types.ts rename to www/types.ts diff --git a/yarn.lock b/yarn.lock index d5dd703b..f005ee23 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1505,10 +1505,10 @@ resolved "https://registry.npmjs.org/@design-sdk/figma-auth-store/-/figma-auth-store-0.0.43.tgz" integrity sha512-5VF1EijfZwzOMq+r4ipQ0aDRk/JSUHOjg9cI7oaD+K+sw2YIjgxSBE05/tvncZhOpmFvDHSHTISYJfUsEWfSUQ== -"@design-sdk/figma-core@^0.0.43": - version "0.0.43" - resolved "https://registry.yarnpkg.com/@design-sdk/figma-core/-/figma-core-0.0.43.tgz#0d19d014daf398ed39046bfd4e7f3d2b78842943" - integrity sha512-7WQ29f4hUOxu4Mu8ZyqbBI5F4DsRJbIjGIcZAUmn7O9/SRR00upTYrl2hdlEnKdE0ImHTYqfISgxjkoYEQgZaQ== +"@design-sdk/figma-core@^0.0.25": + version "0.0.25" + resolved "https://registry.yarnpkg.com/@design-sdk/figma-core/-/figma-core-0.0.25.tgz#7fa28cc7d6e45cd713c5f268d42e4dd4f2b41590" + integrity sha512-6OF7eUbDOlR4/BFtd2FRyDvvUf777OGNbVbNScUOv3Fk/kUXBzMTXX6ZdoRlTx887v/vo3+Lh0D31SG1sm80aA== "@design-sdk/figma-node-conversion@^0.0.43": version "0.0.43" @@ -1531,13 +1531,13 @@ "@design-sdk/figma-node" "^0.0.43" "@design-sdk/figma-types" "^0.0.43" -"@design-sdk/figma-node@^0.0.43": - version "0.0.43" - resolved "https://registry.yarnpkg.com/@design-sdk/figma-node/-/figma-node-0.0.43.tgz#5d468ae73e2b07a787d4e6447cdde7efb4f2ea43" - integrity sha512-Wo3jNL4S8NjqbwZZG4eXe2ut/HVM/vPGaEFoEa8MIJyTslwS+sobiU4TW2qDUYNVZW/L7fxYdHO+sBDQOx0TWw== +"@design-sdk/figma-node@0.0.25", "@design-sdk/figma-node@^0.0.43": + version "0.0.25" + resolved "https://registry.yarnpkg.com/@design-sdk/figma-node/-/figma-node-0.0.25.tgz#c95484cc4b003667ae93e95fa3b585b9fa0b740a" + integrity sha512-GCA5cGDXhvGUQddmSIZgPMhH0eGip9S0yDSQiys1XiKnXsB/CM8/5C+JVosHR1WFMHSlJfU+ytA4IH2yhfysUQ== dependencies: - "@design-sdk/figma-core" "^0.0.43" - "@design-sdk/figma-utils" "^0.0.43" + "@design-sdk/figma-core" "^0.0.25" + "@design-sdk/figma-utils" "^0.0.25" "@reflect-ui/font-utils" "^0.0.1" "@design-sdk/figma-remote-api@^0.0.43": @@ -1581,6 +1581,11 @@ resolved "https://registry.yarnpkg.com/@design-sdk/figma-url/-/figma-url-0.0.46.tgz#8cf8eecbb80685480822734bfa871af6e5fa0daa" integrity sha512-9d8Og45cPxRe3Oh8wzWHhFrxZYfaoBdfP/J0OfYs2yTK7XY/vhz1GGf78aBjGdBdmaShHwfI8RHIhhV03nYKkg== +"@design-sdk/figma-utils@^0.0.25": + version "0.0.25" + resolved "https://registry.yarnpkg.com/@design-sdk/figma-utils/-/figma-utils-0.0.25.tgz#7b7f6632fd8689ef713b27b34a61257accc2052e" + integrity sha512-HarFMa14L9zqg8rhLaCTXhTKFd6tlBno1mnSc/vl8ZVilmdq32OFFlmqS4MjyvrTfyAvbwlEMAhxV1SUQhFhRg== + "@design-sdk/figma-utils@^0.0.43": version "0.0.43" resolved "https://registry.npmjs.org/@design-sdk/figma-utils/-/figma-utils-0.0.43.tgz" @@ -6851,22 +6856,10 @@ resolved "https://registry.npmjs.org/@reflect-ui/cg/-/cg-0.0.5.tgz" integrity sha512-rqqaumLDgk9dGtPgkYy9h5PLlNv8ZVEz/+ktOcJpJE6v9fAQOSH1Wh5WAehpiZTQtKe944GzrFMsb/g8pTabWg== -"@reflect-ui/core@0.0.2-rc.7": - version "0.0.2-rc.7" - resolved "https://registry.yarnpkg.com/@reflect-ui/core/-/core-0.0.2-rc.7.tgz#9d531f5a0b9caab31e7563020044b753700e2bbc" - integrity sha512-EqF4SRU57bfa5DOPET1rv5lROFyMVHLv1xTEIlN6N2gDpXt71QceImWfQp3z3Khqnb4R/p9OhNK6DXGUpozWKw== - -"@reflect-ui/core@0.0.5", "@reflect-ui/core@^0.0.5": - version "0.0.5" - resolved "https://registry.yarnpkg.com/@reflect-ui/core/-/core-0.0.5.tgz#f50ae00e64300c4b698ab5c5374c6ac3bb5de873" - integrity sha512-lA6AYHCF8aSyOvGXbJZcmlB5ccxCaznhxvD8Hg1UjVdhcbLhMWDbzoYqbrkqh+R4im3KnYw5n6pWSSdoWioYhA== - dependencies: - "@reflect-ui/uiutils" "^0.1.2-1" - -"@reflect-ui/core@^0.0.9": - version "0.0.9" - resolved "https://registry.yarnpkg.com/@reflect-ui/core/-/core-0.0.9.tgz#7283a2a3a1edde16282559d11f02e23d3bceda36" - integrity sha512-MNJq+Pc45qZ0IvTYuvzCW2nxupVRfMtmin9vepABo2h1sTKdAmCK2kPfVLea6TNiF1baJDeQg7IyAN45JMuFdA== +"@reflect-ui/core@0.0.12", "@reflect-ui/core@0.0.2-rc.7", "@reflect-ui/core@0.0.5", "@reflect-ui/core@^0.0.5", "@reflect-ui/core@^0.0.9": + version "0.0.12" + resolved "https://registry.yarnpkg.com/@reflect-ui/core/-/core-0.0.12.tgz#f410ecef10ce4ecb2cffdda93056091d68ce2b87" + integrity sha512-Ae/2ImJ70d1PrcVLmQgJhxTr5RZA6wxLeTgxRaATA3nryjp4aiz7pznzd3EqX0zii+7N79Xpk20KCuXJByypuA== dependencies: "@reflect-ui/uiutils" "^0.1.2-1" @@ -9386,7 +9379,7 @@ dependencies: "@types/react" "*" -"@types/react@*", "@types/react@^18", "@types/react@^18.0.24": +"@types/react@*", "@types/react@18.0.24", "@types/react@^17", "@types/react@^18", "@types/react@^18.0.24", "@types/react@^18.0.25": version "18.0.24" resolved "https://registry.yarnpkg.com/@types/react/-/react-18.0.24.tgz#2f79ed5b27f08d05107aab45c17919754cc44c20" integrity sha512-wRJWT6ouziGUy+9uX0aW4YOJxAY0bG6/AOk5AW5QSvZqI7dk6VBIbXvcVgIw/W5Jrl24f77df98GEKTJGOLx7Q== @@ -9395,24 +9388,6 @@ "@types/scheduler" "*" csstype "^3.0.2" -"@types/react@^17": - version "17.0.73" - resolved "https://registry.yarnpkg.com/@types/react/-/react-17.0.73.tgz#23a663c803b18d8b7f4f2bb9b467f2f3fd70787a" - integrity sha512-6AcjgPIVsXTIsFDgsGW0iQhvg0xb2vt2qAWgXyncnVNRaW9ZXTTwAh7RQoh7PzK1AhjPoGDvUBkdAREih9n5oQ== - dependencies: - "@types/prop-types" "*" - "@types/scheduler" "*" - csstype "^3.0.2" - -"@types/react@^18.0.25": - version "18.2.45" - resolved "https://registry.yarnpkg.com/@types/react/-/react-18.2.45.tgz#253f4fac288e7e751ab3dc542000fb687422c15c" - integrity sha512-TtAxCNrlrBp8GoeEp1npd5g+d/OejJHFxS3OWmrPBMFaVQMSN0OFySozJio5BHxTuTeug00AVXVAjfDSfk+lUg== - dependencies: - "@types/prop-types" "*" - "@types/scheduler" "*" - csstype "^3.0.2" - "@types/resemblejs@^4.1.3": version "4.1.3" resolved "https://registry.yarnpkg.com/@types/resemblejs/-/resemblejs-4.1.3.tgz#46d16888952e377b9143484c206b63f6da56e91e" @@ -12892,16 +12867,11 @@ cssesc@^3.0.0: resolved "https://registry.npmjs.org/cssesc/-/cssesc-3.0.0.tgz" integrity sha512-/Tb/JcjK111nNScGob5MNtsntNM1aCNUDipB/TkwZFhyDrrE47SOx/18wF2bbjgc3ZzCSKW1T5nt5EbFoAz/Vg== -csstype@^3.0.10, csstype@^3.0.2, csstype@^3.0.4, csstype@^3.0.8: +csstype@3.1.0, csstype@^3.0.10, csstype@^3.0.2, csstype@^3.0.4, csstype@^3.0.8, csstype@^3.1.1: version "3.1.0" resolved "https://registry.yarnpkg.com/csstype/-/csstype-3.1.0.tgz#4ddcac3718d787cf9df0d1b7d15033925c8f29f2" integrity sha512-uX1KG+x9h5hIJsaKR9xHUeUraxf8IODOwq9JLNPq6BwB04a/xgpq3rcx47l5BZu5zBPlgD342tdke3Hom/nJRA== -csstype@^3.1.1: - version "3.1.3" - resolved "https://registry.yarnpkg.com/csstype/-/csstype-3.1.3.tgz#d80ff294d114fb0e6ac500fbf85b60137d7eff81" - integrity sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw== - cuid@^2.1.8: version "2.1.8" resolved "https://registry.npmjs.org/cuid/-/cuid-2.1.8.tgz"