@neodx/figma - Export API

.changeset/few-bikes-marry.md

@@ -0,0 +1,5 @@
+---
+'@neodx/figma': patch
+---
+
+Rework documentation, add big section about docs migration

.changeset/nasty-zebras-hug.md

@@ -0,0 +1,5 @@
+---
+'@neodx/figma': patch
+---
+
+Reorganize Node Export API for more accurate stages composition

.changeset/new-islands-talk.md

@@ -0,0 +1,5 @@
+---
+'@neodx/autobuild': minor
+---
+
+Add `--flatten` option for `dist` unzipping which results in user-friendly structure

.changeset/ninety-scissors-itch.md

@@ -0,0 +1,5 @@
+---
+'@neodx/svg': patch
+---
+
+Add `resetColors: false` support

.changeset/purple-queens-speak.md

@@ -0,0 +1,5 @@
+---
+'@neodx/log': patch
+---
+
+Inline `cli-truncate` dependency to solve `cjs` imports issue

.changeset/red-ants-grin.md

@@ -0,0 +1,5 @@
+---
+'@neodx/std': patch
+---
+
+Add `shallowEqual`

.changeset/silver-balloons-repeat.md

@@ -0,0 +1,5 @@
+---
+'@neodx/figma': minor
+---
+
+Make Export APIs more consistent,

.changeset/slimy-bobcats-itch.md

@@ -0,0 +1,5 @@
+---
+'@neodx/figma': minor
+---
+
+Introduce new Export API: Exporting published library component

.github/workflows/release.yaml

@@ -35,5 +35,6 @@ jobs:
           version: yarn release-version
 
         env:
+          AUTOBUILD_FORCE_FLATTEN: true
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

README.md

@@ -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! 🚀
 

apps/docs/.vitepress/config.ts

@@ -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: [
@@ -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' }]
+    ]
   }
 });

apps/docs/figma/api/export/export-file-assets.md

@@ -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;
+}
+```

apps/docs/figma/api/export/export-published-components.md

@@ -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;
+}
+```