Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

@neodx/figma - Export API #114

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/few-bikes-marry.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@neodx/figma': patch
---

Rework documentation, add big section about docs migration
5 changes: 5 additions & 0 deletions .changeset/nasty-zebras-hug.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@neodx/figma': patch
---

Reorganize Node Export API for more accurate stages composition
5 changes: 5 additions & 0 deletions .changeset/new-islands-talk.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@neodx/autobuild': minor
---

Add `--flatten` option for `dist` unzipping which results in user-friendly structure
5 changes: 5 additions & 0 deletions .changeset/ninety-scissors-itch.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@neodx/svg': patch
---

Add `resetColors: false` support
5 changes: 5 additions & 0 deletions .changeset/purple-queens-speak.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@neodx/log': patch
---

Inline `cli-truncate` dependency to solve `cjs` imports issue
5 changes: 5 additions & 0 deletions .changeset/red-ants-grin.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@neodx/std': patch
---

Add `shallowEqual`
5 changes: 5 additions & 0 deletions .changeset/silver-balloons-repeat.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@neodx/figma': minor
---

Make Export APIs more consistent,
5 changes: 5 additions & 0 deletions .changeset/slimy-bobcats-itch.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@neodx/figma': minor
---

Introduce new Export API: Exporting published library component
1 change: 1 addition & 0 deletions .github/workflows/release.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -35,5 +35,6 @@ jobs:
version: yarn release-version

env:
AUTOBUILD_FORCE_FLATTEN: true
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ So, `@neodx/figma` is an attempt to create it. Currently, we have the following
See our examples for more details:

- [SVG sprite generation on steroids with Figma export](./examples/svg-magic-with-figma-export) - Integrated showcase of the `@neodx/svg` and `@neodx/figma` packages with real application usage!
- [Export icons from the Community Weather Icons Kit](./examples/figma-simple-export) - A simple step-by-step example of how to use the `@neodx/figma` to export icons.
- [Export icons from the Community Weather Icons Kit](./examples/figma-export-file-assets) - A simple step-by-step example of how to use the `@neodx/figma` to export icons.

We have a some ideas for future development, so stay tuned and feel free to request your own! 🚀

Expand Down
97 changes: 91 additions & 6 deletions apps/docs/.vitepress/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,21 @@ export default defineConfig({
title: 'Neodx',
description: 'Modern solutions for great DX',
themeConfig: {
// https://vitepress.dev/reference/default-theme-config
socialLinks: [{ icon: 'github', link: 'https://github.com/secundant/neodx' }],
footer: {
message: 'Released under the MIT License.',
copyright: 'Copyright © 2023-present Dmitry Remezov'
},
nav: [
{ text: 'Home', link: '/' },
{ text: 'Examples', link: '/markdown-examples' }
{
text: 'Packages',
activeMatch: '^/(log|svg|figma)/',
items: [
{ text: '@neodx/log', link: '/log/', activeMatch: '^/log/' },
{ text: '@neodx/svg', link: '/svg/', activeMatch: '^/svg/' },
{ text: '@neodx/figma', link: '/figma/', activeMatch: '^/figma/' }
]
}
],

sidebar: [
Expand All @@ -33,9 +44,83 @@ export default defineConfig({
{ text: 'Frameworks and bundlers', link: '/svg/frameworks-and-bundlers' },
{ text: 'Automatically reset colors', link: '/svg/colors-reset' }
]
},
{
text: '@neodx/figma',
collapsed: true,
items: [
{ text: 'Getting started', link: '/figma/' },
{ text: 'Motivation', link: '/figma/motivation' },
{
text: 'Recipes',
items: [
{ text: 'Export File Assets', link: '/figma/recipes/export-file-assets' },
{
text: 'Export Published Components',
link: '/figma/recipes/export-published-components'
},
{ text: 'Traverse Figma File', link: '/figma/recipes/traverse-figma-file' }
]
},
{
text: 'API',
items: [
{ text: 'Figma API', link: '/figma/api/figma-api' },
{
text: 'Export API',
link: '/figma/api/export/',
items: [
{ text: 'Export File Assets', link: '/figma/api/export/export-file-assets' },
{
text: 'Export Published Components',
link: '/figma/api/export/export-published-components'
}
]
}
]
},
{
text: 'Node API',
collapsed: true,
items: [
{
text: 'collectNodes',
link: '/figma/api/low-level/collect-nodes'
},
{
text: 'createFileGraph',
link: '/figma/api/low-level/create-file-graph'
},
{
text: 'Common utilities',
link: '/figma/api/low-level/utils'
}
]
},
{
text: 'Low-level Export API',
collapsed: true,
items: [
{
text: 'createExportContext',
link: '/figma/api/low-level/create-export-context'
},
{
text: 'resolveExportedAssets',
link: '/figma/api/low-level/resolve-exported-assets'
},
{
text: 'downloadExportedAssets',
link: '/figma/api/low-level/download-exported-assets'
},
{
text: 'writeDownloadedAssets',
link: '/figma/api/low-level/write-downloaded-assets'
}
]
}
]
}
],

socialLinks: [{ icon: 'github', link: 'https://github.com/secundant/neodx' }]
]
}
});
55 changes: 0 additions & 55 deletions apps/docs/api-examples.md

This file was deleted.

67 changes: 67 additions & 0 deletions apps/docs/figma/api/export/export-file-assets.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# Export file assets API Reference

## CLI

Configuration for `export` command in `.figma.config.js`.

- [Basic configuration](#basic-configuration)

```typescript
export interface ExportFileAssetsCliParams extends BasicConfiguration {
/**
* "file-assets" is using by default, so you don't need to specify it.
*/
type?: 'file-assets';
/**
* Optional if you already defined `fileId` in root configuration.
*/
fileId?: string;
/**
* Path to the output directory of exported files (relative to the current working directory)
*/
output?: string;
}
```

## Node.js

In Node.js, you can use `exportFileAssets` function to export assets from a Figma file.

```typescript
declare function exportFileAssets(params: ExportFileAssetsParams): Promise<void>;
```

- `ctx`: [ExportContext](../low-level/create-export-context.md#createexportcontextparams)
- [Basic configuration](#basic-configuration)

```typescript
export interface ExportFileAssetsParams extends BasicConfiguration {
ctx: ExportContext;
}
```

## Basic configuration

- `write`: [WriteDownloadedAssetsConfig](../low-level/write-downloaded-assets.md#writedownloadedassetsconfig)
- `collect`: [CollectNodesParams](../low-level/collect-nodes.md#collectnodesparams) (except `log`)
- `resolve`: [ResolveExportedAssetsConfig](../low-level/resolve-exported-assets.md#resolveexportedassetsconfig)
- `download`: [DownloadExportedAssetsConfig](../low-level/download-exported-assets.md#downloadexportedassetsconfig)

```typescript
export interface BasicConfiguration {
write?: WriteDownloadedAssetsConfig<AnyGraphNode, GraphNode<DocumentNode>>;
collect?: CollectNodesParams;
/**
* File nodes have their own optional user-defined export settings.
* To cover it, you could pass `resolve.exportAs: "export"`
*
* @example {
* resolve: {
* exportAs: "export",
* }
* }
*/
resolve?: ResolveExportedAssetsConfig<AnyGraphNode, typeof fileGraphResolversMap>;
download?: DownloadExportedAssetsConfig;
}
```
67 changes: 67 additions & 0 deletions apps/docs/figma/api/export/export-published-components.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# Export published components API Reference

## CLI

Configuration for `export` command in `.figma.config.js`.

- [Basic configuration](#basic-configuration)

```typescript
export interface ExportPublishedComponentsCliParams extends BasicConfiguration {
/**
* Required to be passed explicitly.
*/
type: 'published-components';
/**
* Optional if you already defined `fileId` in root configuration.
*/
fileId?: string;
/**
* Path to the output directory of exported files (relative to the current working directory)
*/
output?: string;
}
```

## Node.js

In Node.js, you can use `exportFileAssets` function to export assets from a Figma file.

```typescript
declare function exportPublishedComponents(params: ExportPublishedComponentsParams): Promise<void>;
```

- `ctx`: [ExportContext](../low-level/create-export-context.md#createexportcontextparams)
- [Basic configuration](#basic-configuration)

```typescript
export interface ExportPublishedComponentsParams extends BasicConfiguration {
ctx: ExportContext;
}
```

## Basic configuration

- `write`: [WriteDownloadedAssetsConfig](../low-level/write-downloaded-assets.md#writedownloadedassetsconfig)
- `collect`: [CollectNodesParams](../low-level/collect-nodes.md#collectnodesparams) (except `log`)
- `resolve`: [ResolveExportedAssetsConfig](../low-level/resolve-exported-assets.md#resolveexportedassetsconfig)
- `download`: [DownloadExportedAssetsConfig](../low-level/download-exported-assets.md#downloadexportedassetsconfig)

```typescript
export interface BasicConfiguration {
/**
* Path to the cached file (relative to the output directory)
* @unstable May be changed in the future, use it at your own risk.
*/
cache?: string | false;
write?: WriteDownloadedAssetsConfig<ComponentMetadata, { fileId: string }>;
/**
* Filter components to export.
* @param {ComponentMetadata} component
* @example (component) => component.name.startsWith('Icon/')
*/
filter?: (component: ComponentMetadata) => boolean;
resolve?: ResolveExportedAssetsConfig<ComponentMetadata>;
download?: DownloadExportedAssetsConfig;
}
```
Loading