handoff-app 2.0.0-7 → 2.0.0-9

package/dist/types/config.d.ts

@@ -1,3 +1,4 @@
+import type { EnvValue, EnvSecret, RuntimeEnvReference } from '../config/from-env';
 import { BuildOptions } from 'esbuild';
 import type Handlebars from 'handlebars';
 import { Types as HandoffTypes } from 'handoff-core';
@@ -63,8 +64,8 @@ export type RegisterHandlebarsHelpersContext = {
 };
 export interface NextAppConfig {
     theme?: string;
-    title: string;
-    client: string;
+    title?: string;
+    client?: string;
     google_tag_manager?: string | null | undefined;
     googleTagManager?: string | null | undefined;
     type_copy?: string;
@@ -73,15 +74,17 @@ export interface NextAppConfig {
     typeSort?: string[];
     color_sort?: string[];
     colorSort?: string[];
-    breakpoints: Breakpoints;
+    /** Omit to keep the defaults; a declared block merges onto them rather than replacing them. */
+    breakpoints?: Breakpoints;
     component_sort?: string[];
     componentSort?: string[];
     base_path?: string;
     basePath?: string;
-    attribution: boolean;
+    /** @default true */
+    attribution?: boolean;
     ports?: {
-        app: number;
-        websocket: number;
+        app: EnvValue<number>;
+        websocket: EnvValue<number>;
     };
 }
 /**
@@ -139,13 +142,8 @@ export interface HandoffRuntimeConfig {
     };
     /** Registry-mode host settings. Env-var values are stored as names, never as secrets. */
     registry?: {
-        /** Name of the env var holding the database URL. @default "DATABASE_URL" */
-        databaseUrlEnv?: string;
-        /**
-         * @deprecated Fixed registry secrets are no longer authorized. This option remains parseable
-         * only so existing configuration files do not break.
-         */
-        apiTokenEnv?: string;
+        /** Environment reference to the database URL. @default fromEnv('DATABASE_URL') */
+        databaseUrl?: RuntimeEnvReference<string>;
         database?: {
             /**
              * PostgreSQL is the supported database. `driver` selects the built-in connection driver — how
@@ -168,11 +166,11 @@ export interface HandoffRuntimeConfig {
             adapter?: 'database' | 'vercel-blob' | 'custom';
             /** For `adapter: "custom"` - server-only module path default-exporting a `defineAssetStorage` adapter. */
             module?: string;
-            /** For `adapter: "vercel-blob"` - env var name holding the Blob read/write token. @default "BLOB_READ_WRITE_TOKEN" */
-            tokenEnv?: string;
+            /** For `adapter: "vercel-blob"` - environment reference to the Blob read/write token. @default fromEnv('BLOB_READ_WRITE_TOKEN') */
+            token?: RuntimeEnvReference<string>;
             /** Max bytes kept inline in the database `bytea` column (larger uploads are rejected). @default 4194304 */
             maxInlineBytes?: number;
-            /** Non-secret adapter options (bucket env-var names, region, a custom `providerId`, …). */
+            /** Non-secret options, JSON-encoded into the bundle. Environment references are rejected. Pass variable names instead. */
             options?: Record<string, unknown>;
         };
     };
@@ -181,21 +179,20 @@ export interface HandoffRuntimeConfig {
      * `mode: 'workspace'` plus this block — it is not a third runtime mode.
      */
     registryConnection?: {
-        url?: string;
-        /** @default "HANDOFF_REGISTRY_URL" */
-        urlEnv?: string;
-        /** @default "HANDOFF_REGISTRY_ACCESS_TOKEN" */
-        accessTokenEnv?: string;
+        /** @default fromEnv('HANDOFF_REGISTRY_URL', { default: '' }) */
+        url?: EnvValue<string>;
+        /** @default fromEnv('HANDOFF_REGISTRY_ACCESS_TOKEN', { default: '' }) */
+        accessToken?: EnvSecret<string>;
     };
 }
 export interface Config {
-    dev_access_token?: string | null | undefined;
-    devAccessToken?: string | null | undefined;
-    figma_project_id?: string | null | undefined;
-    figmaProjectId?: string | null | undefined;
-    exportsOutputDirectory?: string;
-    sitesOutputDirectory?: string;
-    useVariables?: boolean;
+    dev_access_token?: EnvSecret<string | null>;
+    devAccessToken?: EnvSecret<string | null>;
+    figma_project_id?: EnvValue<string | null>;
+    figmaProjectId?: EnvValue<string | null>;
+    exportsOutputDirectory?: EnvValue<string>;
+    sitesOutputDirectory?: EnvValue<string>;
+    useVariables?: EnvValue<boolean>;
     /**
      * Configuration for React component docs generation (handoff-docgen).
      */
@@ -276,6 +273,9 @@ export interface Config {
         validateComponent?: (component: TransformComponentTokensResult) => Promise<Record<string, ValidationResult>>;
         /**
          * Optional hook to override the SSR build configuration used in the ssrRenderPlugin
+         *
+         * Stylesheet loaders are re-applied after this hook, so a `.css`/`.scss`/`.sass` import stays out
+         * of the JavaScript graph whatever the hook returns.
          * @param config - The default esbuild configuration
          * @returns Modified esbuild configuration
          * @example
@@ -289,6 +289,9 @@ export interface Config {
         ssrBuildConfig?: (config: BuildOptions) => BuildOptions;
         /**
          * Optional hook to override the client-side build configuration used in the ssrRenderPlugin
+         *
+         * Stylesheet loaders are re-applied after this hook, so a `.css`/`.scss`/`.sass` import stays out
+         * of the JavaScript graph whatever the hook returns.
          * @param config - The default esbuild configuration
          * @returns Modified esbuild configuration
          * @example
@@ -387,7 +390,29 @@ export interface ClientRuntimeConfig {
      */
     connected: boolean;
 }
-export type ClientConfig = Pick<Config, 'app' | 'exportsOutputDirectory' | 'sitesOutputDirectory' | 'assets_zip_links' | 'useVariables'> & {
+/** Values available after config loading. Deferred references retain their names. */
+export type ResolvedConfig = Omit<Config, 'dev_access_token' | 'devAccessToken' | 'figma_project_id' | 'figmaProjectId' | 'exportsOutputDirectory' | 'sitesOutputDirectory' | 'useVariables' | 'app' | 'runtime'> & {
+    dev_access_token?: string | null;
+    devAccessToken?: string | null;
+    figma_project_id?: string | null;
+    figmaProjectId?: string | null;
+    exportsOutputDirectory?: string;
+    sitesOutputDirectory?: string;
+    useVariables?: boolean;
+    app?: Omit<NextAppConfig, 'ports'> & {
+        ports?: {
+            app: number;
+            websocket: number;
+        };
+    };
+    runtime?: Omit<HandoffRuntimeConfig, 'registryConnection'> & {
+        registryConnection?: {
+            url?: string;
+            accessToken?: string;
+        };
+    };
+};
+export type ClientConfig = Pick<ResolvedConfig, 'app' | 'exportsOutputDirectory' | 'sitesOutputDirectory' | 'assets_zip_links' | 'useVariables'> & {
     runtime: ClientRuntimeConfig;
 };
 export interface RuntimeConfigComponentOptions {

package/docs/api.md

@@ -29,6 +29,37 @@ handoff.fetch();
 3. Build your typescript `tsc`
 4. Run your project `node handoff.js`
 
+## Configuration profiles
+
+A profile is a sidecar config file, `handoff.config.<profile>.*`, that merges
+onto the base config. The CLI selects one with `--profile`, and the class takes
+it as a constructor option. Handoff reads `HANDOFF_PROFILE` when neither is
+given.
+
+```js
+const handoff = new Handoff({ profile: 'registry' });
+```
+
+A profile also names the saved registry login that `publish` and `checkout`
+use, so one workspace can address several registries. `profileWithoutConfig`
+decides what a profile may resolve to when it has no config file:
+`'saved-login'` accepts a name a saved login uses, and `'any'` accepts any
+valid name, which is how `login` creates a new one.
+
+```js
+const handoff = new Handoff({ profile: 'staging', profileWithoutConfig: 'saved-login' });
+```
+
+`defineConfig` types a profile as well as a base config.
+
+```ts
+import { defineConfig } from 'handoff-app';
+
+export default defineConfig({
+  runtime: { registry: { database: { driver: 'neon' } } },
+});
+```
+
 ## Methods
 
 Methods of the handoff class can be called to run actions in the

package/docs/cli.md

@@ -58,9 +58,9 @@ Commands:
 
   db:migrate [opts] - Runs registry database migrations (Drizzle / PostgreSQL). Reads the project config and database env vars, applies the package-owned migration set, and runs independently of `build`.
 
-  login --url <registry-url> - Authorizes this workspace in the browser and stores a revocable token in `.handoff/cli-auth.json`.
+  login [--profile <name>] --url <registry-url> - Authorizes this workspace in the browser and stores a revocable token in `.handoff/cli-auth.json`, under the selected profile.
 
-  logout [--url <registry-url>] - Revokes the saved token when possible, then removes the local credential.
+  logout [--profile <name>] [--url <registry-url>] [--all] - Revokes the saved token when possible, then removes the local credential of the selected profile, or of every profile with `--all`.
 
   make
     make:component <name> [opts] - Creates a new catalog item with a declaration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-app",
-  "version": "2.0.0-7",
+  "version": "2.0.0-9",
   "description": "Automated documentation toolchain for building client side documentation from figma",
   "author ": {
     "name": "Convertiv",

package/src/app/components/Component/PageSliceResolver.tsx

@@ -44,6 +44,7 @@ export const PageSliceResolver: React.FC<PageSliceResolverProps> = ({
           showPreview={slice.showPreview}
           showCodeHighlight={slice.showCodeHighlight}
           defaultHeight={slice.defaultHeight}
+          defaultWidth={slice.defaultWidth}
           filterBy={slice.filterBy}
           codeHighlight={codeHighlight}
         />