feat: support overridableVariables in recipes; add overrides prop to ActionButton

.changeset/evil-drinks-sink.md

@@ -0,0 +1,6 @@
+---
+"@seed-design/react": patch
+"@seed-design/css": patch
+---
+
+`ActionButton`에서 `overrides` prop을 통해 배경 색상을 오버라이드할 수 있도록 합니다.

docs/components/example/action-button-overriding.tsx

@@ -0,0 +1,26 @@
+import { ActionButton } from "seed-design/ui/action-button";
+import { vars } from "@seed-design/css/vars";
+import { HStack } from "@seed-design/react";
+
+export default function ActionButtonOverriding() {
+  return (
+    <HStack gap="x3">
+      <ActionButton
+        overrides={{
+          "--seed-action-button-enabled-background": vars.$color.bg.informativeSolid,
+          "--seed-action-button-active-background": vars.$color.bg.informativeSolidPressed,
+        }}
+      >
+        라벨
+      </ActionButton>
+      <ActionButton
+        overrides={{
+          "--seed-action-button-enabled-background": `linear-gradient(135deg, ${vars.$color.palette.purple400} 0%, ${vars.$color.palette.purple800} 100%)`,
+          "--seed-action-button-active-background": `linear-gradient(135deg, ${vars.$color.palette.purple500} 0%, ${vars.$color.palette.purple900} 100%)`,
+        }}
+      >
+        라벨
+      </ActionButton>
+    </HStack>
+  );
+}

docs/components/type-table/get-union-literals.ts

@@ -0,0 +1,51 @@
+import { Project } from "ts-morph";
+import * as path from "node:path";
+
+export interface UnionLiteralTableProps {
+  path: string;
+  name: string;
+}
+
+export interface UnionLiteralResult {
+  name: string;
+  literals: string[];
+}
+
+const project = new Project({ skipAddingFilesFromTsConfig: true });
+
+export async function getUnionLiterals({
+  path: filePath,
+  name,
+}: UnionLiteralTableProps): Promise<UnionLiteralResult> {
+  const resolvedPath = resolveTypePath(filePath);
+  const sourceFile = project.addSourceFileAtPath(resolvedPath);
+
+  const typeAlias = sourceFile.getTypeAlias(name);
+
+  if (!typeAlias) throw new Error(`Type "${name}" not found in ${filePath}`);
+
+  const type = typeAlias.getType();
+  if (!type) throw new Error(`Type "${name}" not found in ${filePath}`);
+
+  const literals = (type.isUnion() ? type.getUnionTypes() : [type])
+    .map((t) => t.getText())
+    .filter((v): v is string => !!v);
+
+  return { name, literals };
+}
+
+// TODO: do this better with require.resolve or something
+// import.meta.resolve will work but not currently supported in Next.js
+function resolveTypePath(filePath: string): string {
+  if (filePath.startsWith("@seed-design/")) {
+    const packagePath = filePath.replace("@seed-design/", "");
+
+    return path.join(process.cwd(), "../packages", `${packagePath}.d.ts`);
+  }
+
+  if (filePath.startsWith("./") || filePath.startsWith("../")) {
+    return path.resolve(process.cwd(), filePath);
+  }
+
+  return filePath;
+}

docs/components/type-table/remark-react-type-table.tsx

@@ -11,7 +11,7 @@ import type { MdxJsxAttribute, MdxJsxFlowElement } from "mdast-util-mdx-jsx";
 import { dirname } from "node:path";
 import { print } from "recast";
 import type { Transformer } from "unified";
-import { visit } from "unist-util-visit";
+import { visit, SKIP } from "unist-util-visit";
 import { getReactTypeTableOutput, type ReactTypeTableProps } from "./get-react-type-table";
 
 function expressionToAttribute(key: string, value: Expression): MdxJsxAttribute {
@@ -182,7 +182,8 @@ export function remarkReactTypeTable({
       }
 
       queue.push(run());
-      return "skip";
+
+      return SKIP;
     });
 
     await Promise.all(queue);

docs/components/type-table/remark-union-literal-table.tsx

@@ -0,0 +1,85 @@
+import type { Root } from "mdast";
+import type { Transformer } from "unified";
+import { visit, SKIP } from "unist-util-visit";
+import { getUnionLiterals } from "./get-union-literals";
+
+export interface RemarkUnionLiteralTableOptions {
+  /**
+   * @defaultValue 'union-literal-table'
+   */
+  name?: string;
+}
+
+/**
+ * Compile `union-literal-table` into a simple table at build time
+ */
+export function remarkUnionLiteralTable({
+  name = "union-literal-table",
+}: RemarkUnionLiteralTableOptions = {}): Transformer<Root, Root> {
+  return async (tree) => {
+    const queue: Promise<void>[] = [];
+
+    visit(tree, "mdxJsxFlowElement", (node) => {
+      if (node.name !== name) return;
+
+      const props: Record<string, string> = {};
+
+      for (const attr of node.attributes) {
+        if (attr.type !== "mdxJsxAttribute" || typeof attr.value !== "string")
+          throw new Error("`union-literal-table` does not support non-string attributes");
+
+        props[attr.name] = attr.value;
+      }
+
+      async function run() {
+        const result = await getUnionLiterals({
+          path: props.path,
+          name: props.name,
+        });
+
+        // Create a proper markdown table AST structure
+        const tableNode = {
+          type: "table",
+          align: ["left"],
+          children: [
+            {
+              type: "tableRow",
+              children: [
+                {
+                  type: "tableCell",
+                  children: [
+                    {
+                      type: "text",
+                      value: "Possible Values",
+                    },
+                  ],
+                },
+              ],
+            },
+            ...result.literals.map((literal) => ({
+              type: "tableRow",
+              children: [
+                {
+                  type: "tableCell",
+                  children: [
+                    {
+                      type: "inlineCode",
+                      value: literal,
+                    },
+                  ],
+                },
+              ],
+            })),
+          ],
+        };
+
+        Object.assign(node, tableNode);
+      }
+
+      queue.push(run());
+      return SKIP;
+    });
+
+    await Promise.all(queue);
+  };
+}

docs/content/react/components/action-button.mdx

@@ -173,3 +173,20 @@ Ghost variant를 시각적으로 정렬해야 할 때 유용합니다.
   }
   ```
 </ComponentExample>
+
+### Overriding CSS Variables
+
+<ComponentExample name="action-button-overriding">
+  ```json doc-gen:file
+  {
+    "file": "./components/example/action-button-overriding.tsx",
+    "codeblock": true
+  }
+  ```
+</ComponentExample>
+
+#### Overridable CSS Variables
+
+`overrides` prop을 통해 오버라이드할 수 있는 CSS 변수 목록입니다.
+
+<union-literal-table path="@seed-design/css/recipes/action-button" name="ActionButtonOverridableVariable" />

docs/source.config.ts

@@ -3,6 +3,7 @@ import { remarkNpm } from "fumadocs-core/mdx-plugins";
 import { defineConfig, defineDocs, frontmatterSchema } from "fumadocs-mdx/config";
 import { typeTableGenerator } from "./components/type-table/generator";
 import { remarkReactTypeTable } from "./components/type-table/remark-react-type-table";
+import { remarkUnionLiteralTable } from "./components/type-table/remark-union-literal-table";
 import z from "zod";
 
 export const docs = defineDocs({

ecosystem/qvism/core/src/dts.ts

@@ -61,7 +61,7 @@ export function generateRecipeDts(definition: RecipeDefinition<RecipeVariantReco
     definition.defaultVariants,
   );
 
-  return outdent`
+  const base = outdent`
   declare interface ${capitalizedName}Variant {
     ${variantInterface}
   }
@@ -81,7 +81,17 @@ export function generateRecipeDts(definition: RecipeDefinition<RecipeVariantReco
       props: T,
     ) => [${capitalizedName}VariantProps, Omit<T, keyof ${capitalizedName}VariantProps>];
   }
-  `;
+`;
+
+  if (!definition.overridableVariables || definition.overridableVariables.length === 0) {
+    return base;
+  }
+
+  return outdent`${base}
+export declare type ${capitalizedName}OverridableVariable = ${definition.overridableVariables
+    .map(stringLiteralType)
+    .join(" | ")};
+`;
 }
 
 export function generateSlotRecipeDts(
@@ -95,7 +105,7 @@ export function generateSlotRecipeDts(
   );
   const slotNameType = definition.slots.map((slot) => `"${slot}"`).join(" | ");
 
-  return outdent`
+  const base = outdent`
   declare interface ${capitalizedName}Variant {
     ${variantInterface}
   }
@@ -117,7 +127,17 @@ export function generateSlotRecipeDts(
       props: T,
     ) => [${capitalizedName}VariantProps, Omit<T, keyof ${capitalizedName}VariantProps>];
   }
-  `;
+`;
+
+  if (!definition.overridableVariables || definition.overridableVariables.length === 0) {
+    return base;
+  }
+
+  return outdent`${base}  
+export declare type ${capitalizedName}OverridableVariable = ${definition.overridableVariables
+    .map(stringLiteralType)
+    .join(" | ")};
+`;
 }
 
 export function generateDts(definition: RecipeKindDefinition): string {

ecosystem/qvism/core/src/types.ts

@@ -90,6 +90,7 @@ export type RecipeCompoundVariant<T> = T & {
 
 export interface RecipeDefinition<T extends RecipeVariantRecord = RecipeVariantRecord> {
   name: string;
+  overridableVariables?: CssVarKey[];
   base: StyleObject;
   variants: T;
   compoundVariants?: Pretty<RecipeCompoundVariant<RecipeCompoundSelection<T>>>[];
@@ -113,6 +114,7 @@ export interface SlotRecipeDefinition<
   T extends SlotRecipeVariantRecord<S> = SlotRecipeVariantRecord<S>,
 > {
   name: string;
+  overridableVariables?: CssVarKey[];
   slots: S[] | Readonly<S[]>;
   base: SlotRecord<S, StyleObject>;
   variants: T;